From ebbe292a91dd9ced6edc09f3d112fc82e656af03 Mon Sep 17 00:00:00 2001 From: David Hall Date: Tue, 21 Feb 2023 21:33:28 -0700 Subject: [PATCH] Fixed LOGPALETTE structure and associated functions --- PInvoke/Gdi32/WinGdi.Color.cs | 2829 +++--- PInvoke/Kernel32/AppModel.cs | 5091 +++++----- PInvoke/Ole/Ole32/OCIdl.cs | 2 +- PInvoke/Ole/Ole32/OleIdl.cs | 13756 +++++++++++++-------------- PInvoke/Shared/WinGdi/WinGdi.LOGPALETTE.cs | 160 +- UnitTests/PInvoke/Gdi32/Gdi32Tests.cs | 8 + 6 files changed, 10957 insertions(+), 10889 deletions(-) diff --git a/PInvoke/Gdi32/WinGdi.Color.cs b/PInvoke/Gdi32/WinGdi.Color.cs index 21e73379..8d3d0934 100644 --- a/PInvoke/Gdi32/WinGdi.Color.cs +++ b/PInvoke/Gdi32/WinGdi.Color.cs @@ -1,644 +1,1176 @@ using System; using System.Runtime.InteropServices; using System.Text; -using Vanara.Extensions; +using Vanara.InteropServices; -namespace Vanara.PInvoke +namespace Vanara.PInvoke; + +public static partial class Gdi32 { - public static partial class Gdi32 + /// + /// The EnumICMProfilesProcCallback callback is an application-defined callback function that processes color profile data + /// from EnumICMProfiles . + /// + /// Pointer to the file name of the color profile. + /// Data supplied by the application that is passed to the callback function by the EnumICMProfiles function. + /// + /// This function must return a positive value to continue enumeration, or zero to stop enumeration. It may not return a negative value. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/wingdi/nc-wingdi-icmenumprocw ICMENUMPROCW Icmenumprocw; int Icmenumprocw( + // LPWSTR Arg1, LPARAM Arg2 ) {...} + [PInvokeData("wingdi.h", MSDNShortId = "6e8f4ce5-c546-4e6a-8f35-4a22d60b6754")] + [UnmanagedFunctionPointer(CallingConvention.Winapi, CharSet = CharSet.Auto)] + public delegate int EnumICMProfilesProcCallback(string lpszFilename, IntPtr lParam); + + /// Specifies how the output image should be prepared. + [PInvokeData("wingdi.h", MSDNShortId = "9a080f60-0bce-46b6-b8a8-f534ff83a0a8")] + public enum CA_FLAGS : ushort + { + /// Specifies that the negative of the original image should be displayed. + CA_NEGATIVE = 0x0001, + + /// + /// Specifies that a logarithmic function should be applied to the final density of the output colors. This will increase the + /// color contrast when the luminance is low. + /// + CA_LOG_FILTER = 0x0002, + } + + /// Constants used for . + [PInvokeData("wingdi.h", MSDNShortId = "eb922411-0808-4404-bdaf-bf29d0cad379")] + public enum CS { /// - /// The EnumICMProfilesProcCallback callback is an application-defined callback function that processes color profile data - /// from EnumICMProfiles . - /// - /// Pointer to the file name of the color profile. - /// Data supplied by the application that is passed to the callback function by the EnumICMProfiles function. - /// - /// This function must return a positive value to continue enumeration, or zero to stop enumeration. It may not return a negative value. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/wingdi/nc-wingdi-icmenumprocw ICMENUMPROCW Icmenumprocw; int Icmenumprocw( - // LPWSTR Arg1, LPARAM Arg2 ) {...} - [PInvokeData("wingdi.h", MSDNShortId = "6e8f4ce5-c546-4e6a-8f35-4a22d60b6754")] - [UnmanagedFunctionPointer(CallingConvention.Winapi, CharSet = CharSet.Auto)] - public delegate int EnumICMProfilesProcCallback(string lpszFilename, IntPtr lParam); - - /// Specifies how the output image should be prepared. - [PInvokeData("wingdi.h", MSDNShortId = "9a080f60-0bce-46b6-b8a8-f534ff83a0a8")] - public enum CA_FLAGS : ushort - { - /// Specifies that the negative of the original image should be displayed. - CA_NEGATIVE = 0x0001, - - /// - /// Specifies that a logarithmic function should be applied to the final density of the output colors. This will increase the - /// color contrast when the luminance is low. - /// - CA_LOG_FILTER = 0x0002, - } - - /// Constants used for . - [PInvokeData("wingdi.h", MSDNShortId = "eb922411-0808-4404-bdaf-bf29d0cad379")] - public enum CS - { - /// - /// Map the colors to the target device's color gamut. This enables color proofing. All subsequent draw commands to the DC will - /// render colors as they would appear on the target device. - /// - CS_ENABLE = 0x00000001, - - /// Disable color proofing. - CS_DISABLE = 0x00000002, - - /// If color management is enabled for the target profile, disable it and delete the concatenated transform. - CS_DELETE_TRANSFORM = 0x00000003, - } - - /// Turns on and off image color management. - [PInvokeData("wingdi.h", MSDNShortId = "40d70c1f-c580-43c4-b44b-6c9388e138fb")] - public enum ICM - { - /// Turns off color management. Turns on old-style color correction of halftones. - ICM_OFF = 1, - - /// Turns on color management. Turns off old-style color correction of halftones. - ICM_ON = 2, - - /// Queries the current state of color management. - ICM_QUERY = 3, - - /// - /// Turns off color management inside DC. Under Windows 2000, also turns off old-style color correction of halftones. Not - /// supported under Windows 95. - /// - ICM_DONE_OUTSIDEDC = 4, - } - - /// The type of standard light source under which the image is viewed. - [PInvokeData("wingdi.h", MSDNShortId = "9a080f60-0bce-46b6-b8a8-f534ff83a0a8")] - public enum ILLUMINANT : ushort - { - /// Device's default. Standard used by output devices. - ILLUMINANT_DEVICE_DEFAULT = 0, - - /// Tungsten lamp. - ILLUMINANT_A = 1, - - /// Noon sunlight. - ILLUMINANT_B = 2, - - /// NTSC daylight. - ILLUMINANT_C = 3, - - /// Normal print. - ILLUMINANT_D50 = 4, - - /// Bond paper print. - ILLUMINANT_D55 = 5, - - /// Standard daylight. Standard for CRTs and pictures. - ILLUMINANT_D65 = 6, - - /// Northern daylight. - ILLUMINANT_D75 = 7, - - /// Cool white lamp. - ILLUMINANT_F2 = 8, - - /// Same as ILLUMINANT_A. - ILLUMINANT_TUNGSTEN = ILLUMINANT_A, - - /// Same as ILLUMINANT_C. - ILLUMINANT_DAYLIGHT = ILLUMINANT_C, - - /// Same as ILLUMINANT_F2. - ILLUMINANT_FLUORESCENT = ILLUMINANT_F2, - - /// Same as ILLUMINANT_C. - ILLUMINANT_NTSC = ILLUMINANT_C, - } - - /// Color space type. - [PInvokeData("wingdi.h", MSDNShortId = "b08aec07-6ac0-47be-8dc9-d604d94dedde")] - public enum LCSCSTYPE : uint - { - /// - /// Color values are calibrated RGB values. The values are translated using the endpoints specified by the lcsEndpoints member - /// before being passed to the device. - /// - LCS_CALIBRATED_RGB = 0, - - /// Color values are values are sRGB values. - LCS_sRGB = 0x73524742, - - /// Color values are Windows default color space color values. - LCS_WINDOWS_COLOR_SPACE = 0x57696e20, - } - - /// The gamut mapping method. - [PInvokeData("wingdi.h", MSDNShortId = "b08aec07-6ac0-47be-8dc9-d604d94dedde")] - [Flags] - public enum LCSGAMUTMATCH : uint - { - /// Maintain saturation. Used for business charts and other situations in which undithered colors are required. - LCS_GM_BUSINESS = 0x00000001, - - /// Maintain colorimetric match. Used for graphic designs and named colors. - LCS_GM_GRAPHICS = 0x00000002, - - /// Maintain contrast. Used for photographs and natural images. - LCS_GM_IMAGES = 0x00000004, - - /// Maintain the white point. Match the colors to their nearest color in the destination gamut. - LCS_GM_ABS_COLORIMETRIC = 0x00000008, - } - - /// The current state of the system (physical) palette. - [PInvokeData("wingdi.h", MSDNShortId = "0a9e7906-2f81-4fda-b03d-86feb0755327")] - public enum SYSPAL - { - /// The given device context is invalid or does not support a color palette. - SYSPAL_ERROR = 0, - - /// The system palette contains static colors that will not change when an application realizes its logical palette. - SYSPAL_STATIC = 1, - - /// The system palette contains no static colors except black and white. - SYSPAL_NOSTATIC = 2, - - /// The system palette contains no static colors. - SYSPAL_NOSTATIC256 = 3, - } - - /// The AnimatePalette function replaces entries in the specified logical palette. - /// A handle to the logical palette. - /// The first logical palette entry to be replaced. - /// The number of entries to be replaced. - /// A pointer to the first member in an array of PALETTEENTRY structures used to replace the current entries. - /// - /// If the function succeeds, the return value is nonzero. - /// If the function fails, the return value is zero. - /// - /// - /// - /// An application can determine whether a device supports palette operations by calling the GetDeviceCaps function and specifying - /// the RASTERCAPS constant. - /// - /// - /// The AnimatePalette function only changes entries with the PC_RESERVED flag set in the corresponding palPalEntry - /// member of the LOGPALETTE structure. - /// - /// If the given palette is associated with the active window, the colors in the palette are replaced immediately. - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/wingdi/nf-wingdi-animatepalette BOOL AnimatePalette( HPALETTE hPal, UINT - // iStartIndex, UINT cEntries, const PALETTEENTRY *ppe ); - [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] - [PInvokeData("wingdi.h", MSDNShortId = "65dd45e2-39a4-4a94-bd14-b0c8e4a609a3")] - [return: MarshalAs(UnmanagedType.Bool)] - public static extern bool AnimatePalette(HPALETTE hPal, uint iStartIndex, uint cEntries, [In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 2)] PALETTEENTRY[] ppe); - - /// - /// The CheckColorsInGamut function determines whether a specified set of RGB triples lies in the output gamut of a specified - /// device. The RGB triples are interpreted in the input logical color space. - /// - /// Handle to the device context whose output gamut to be checked. - /// Pointer to an array of RGB triples to check. - /// - /// Pointer to the buffer in which the results are to be placed. This buffer must be at least as large as nCount bytes. - /// - /// The number of elements in the array of triples. - /// - /// If this function succeeds, the return value is a nonzero value. - /// If this function fails, the return value is zero. - /// - /// - /// - /// The function places the test results in the buffer pointed to by lpBuffer. Each byte in the buffer corresponds to an RGB triple, - /// and has an unsigned value between CM_IN_GAMUT (= 0) and CM_OUT_OF_GAMUT (= 255). The value 0 denotes that the color is in gamut, - /// while a nonzero value denotes that it is out of gamut. For any integer n such that 0 < n < 255, a result value of n + 1 - /// indicates that the corresponding color is at least as far out of gamut as would be indicated by a result value of n, as specified - /// by the ICC Profile Format Specification. For more information on the ICC Profile Format Specification, see the sources listed in - /// Further Information. - /// - /// - /// Note that for this function to succeed, WCS must be enabled for the device context handle that is passed in through the hDC - /// parameter. WCS can be enabled for a device context handle by calling the SetICMMode function. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/wingdi/nf-wingdi-checkcolorsingamut BOOL CheckColorsInGamut( HDC hdc, - // LPRGBTRIPLE lpRGBTriple, LPVOID dlpBuffer, DWORD nCount ); - [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] - [PInvokeData("wingdi.h", MSDNShortId = "87bee1a6-e3dd-4d0b-ad8a-9584833d9463")] - [return: MarshalAs(UnmanagedType.Bool)] - public static extern bool CheckColorsInGamut(HDC hdc, [In] RGBTRIPLE[] lpRGBTriple, IntPtr dlpBuffer, uint nCount); - - /// - /// The ColorCorrectPalette function corrects the entries of a palette using the WCS 1.0 parameters in the specified device context. - /// - /// Specifies a device context whose WCS parameters to use. - /// Specifies the handle to the palette to be color corrected. - /// Specifies the first entry in the palette to be color corrected. - /// Specifies the number of entries to color correct. - /// - /// If this function succeeds, the return value is TRUE. - /// If this function fails, the return value is FALSE. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/wingdi/nf-wingdi-colorcorrectpalette BOOL ColorCorrectPalette( HDC hdc, - // HPALETTE hPal, DWORD deFirst, DWORD num ); - [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] - [PInvokeData("wingdi.h", MSDNShortId = "e7680521-fb1e-4292-945f-867964dac1ab")] - [return: MarshalAs(UnmanagedType.Bool)] - public static extern bool ColorCorrectPalette(HDC hdc, HPALETTE hPal, uint deFirst, uint num); - - /// The ColorMatchToTarget function enables you to preview colors as they would appear on the target device. - /// Specifies the device context for previewing, generally the screen. - /// Specifies the target device context, generally a printer. - /// - /// A constant that can have one of the following values. - /// - /// - /// Value - /// Meaning - /// - /// - /// CS_ENABLE - /// /// Map the colors to the target device's color gamut. This enables color proofing. All subsequent draw commands to the DC will /// render colors as they would appear on the target device. - /// - /// - /// - /// CS_DISABLE - /// Disable color proofing. - /// - /// - /// CS_DELETE_TRANSFORM - /// If color management is enabled for the target profile, disable it and delete the concatenated transform. - /// - /// - /// - /// - /// If this function succeeds, the return value is TRUE. - /// If this function fails, the return value is FALSE. - /// - /// - /// - /// ColorMatchToTarget can be used to proof the colors of a color output device on another color output device. Setting the - /// uiAction parameter to CS_ENABLE causes all subsequent drawing commands to the DC to render colors as they would appear on the - /// target device. If uiAction is set to CS_DISABLE, proofing is turned off. However, the current color transform is not deleted from - /// the DC. It is just inactive. - /// - /// - /// When ColorMatchToTarget is called, the color transform for the target device is performed first, and then the transform to - /// the preview device is applied to the results of the first transform. This is used primarily for checking gamut mapping - /// conditions. Before using this function, you must enable WCS for both device contexts. - /// - /// - /// This function cannot be cascaded. While color mapping to the target is enabled by setting uiAction to CS_ENABLE, application - /// changes to the color space or gamut mapping method are ignored. Those changes then take effect when color mapping to the target - /// is disabled. - /// - /// - /// Note A memory leak will not occur if an application does not delete a transform using CS_DELETE_TRANSFORM. The transform - /// will be deleted when either the device context (DC) is closed, or when the application color space is deleted. However if the - /// transform is not going to be used again, or if the application will not be performing any more color matching on the DC, it - /// should explicitly delete the transform to free the memory it occupies. - /// - /// - /// The uiAction parameter should only be set to CS_DELETE_TRANSFORM if color management is enabled before the - /// ColorMatchToTarget function is called. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/wingdi/nf-wingdi-colormatchtotarget BOOL ColorMatchToTarget( HDC hdc, HDC - // hdcTarget, DWORD action ); - [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] - [PInvokeData("wingdi.h", MSDNShortId = "eb922411-0808-4404-bdaf-bf29d0cad379")] - [return: MarshalAs(UnmanagedType.Bool)] - public static extern bool ColorMatchToTarget(HDC hdc, HDC hdcTarget, CS action); + /// + CS_ENABLE = 0x00000001, - /// The CreateColorSpace function creates a logical color space. - /// Pointer to the LOGCOLORSPACE data structure. - /// - /// If this function succeeds, the return value is a handle that identifies a color space. - /// If this function fails, the return value is NULL. - /// - /// - /// When the color space is no longer needed, use DeleteColorSpace to delete it. - /// - /// Windows 95/98/Me:CreateColorSpaceW is supported by the Microsoft Layer for Unicode. To use this, you must add - /// certain files to your application, as outlined in Microsoft Layer for Unicode on Windows 95/98/Me Systems. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/wingdi/nf-wingdi-createcolorspacea HCOLORSPACE CreateColorSpaceA( - // LPLOGCOLORSPACEA lplcs ); - [DllImport(Lib.Gdi32, SetLastError = false, CharSet = CharSet.Auto)] - [PInvokeData("wingdi.h", MSDNShortId = "c3fc798c-4bb9-4010-87d4-edc0005b7698")] - public static extern SafeHCOLORSPACE CreateColorSpace(in LOGCOLORSPACE lplcs); + /// Disable color proofing. + CS_DISABLE = 0x00000002, - /// The CreateHalftonePalette function creates a halftone palette for the specified device context (DC). - /// A handle to the device context. - /// - /// If the function succeeds, the return value is a handle to a logical halftone palette. - /// If the function fails, the return value is zero. - /// - /// - /// - /// An application should create a halftone palette when the stretching mode of a device context is set to HALFTONE. The logical - /// halftone palette returned by CreateHalftonePalette should then be selected and realized into the device context before the - /// StretchBlt or StretchDIBits function is called. - /// - /// When you no longer need the palette, call the DeleteObject function to delete it. - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/wingdi/nf-wingdi-createhalftonepalette HPALETTE CreateHalftonePalette( HDC - // hdc ); - [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] - [PInvokeData("wingdi.h", MSDNShortId = "ba9dfa0c-98df-4922-acba-d00e9b4b0fb0")] - public static extern SafeHPALETTE CreateHalftonePalette(HDC hdc); + /// If color management is enabled for the target profile, disable it and delete the concatenated transform. + CS_DELETE_TRANSFORM = 0x00000003, + } - /// The CreatePalette function creates a logical palette. - /// A pointer to a LOGPALETTE structure that contains information about the colors in the logical palette. - /// - /// If the function succeeds, the return value is a handle to a logical palette. - /// If the function fails, the return value is NULL. - /// - /// - /// - /// An application can determine whether a device supports palette operations by calling the GetDeviceCaps function and specifying - /// the RASTERCAPS constant. - /// - /// - /// Once an application creates a logical palette, it can select that palette into a device context by calling the SelectPalette - /// function. A palette selected into a device context can be realized by calling the RealizePalette function. - /// - /// When you no longer need the palette, call the DeleteObject function to delete it. - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/wingdi/nf-wingdi-createpalette HPALETTE CreatePalette( const LOGPALETTE - // *plpal ); - [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] - [PInvokeData("wingdi.h", MSDNShortId = "f3462198-9360-4b77-ac62-9fe21ec666be")] - public static extern SafeHPALETTE CreatePalette([In] LOGPALETTE plpal); + /// Turns on and off image color management. + [PInvokeData("wingdi.h", MSDNShortId = "40d70c1f-c580-43c4-b44b-6c9388e138fb")] + public enum ICM + { + /// Turns off color management. Turns on old-style color correction of halftones. + ICM_OFF = 1, - /// The DeleteColorSpace function removes and destroys a specified color space. - /// Specifies the handle to a color space to delete. - /// - /// If this function succeeds, the return value is TRUE. - /// If this function fails, the return value is FALSE. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/wingdi/nf-wingdi-deletecolorspace BOOL DeleteColorSpace( HCOLORSPACE hcs ); - [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] - [PInvokeData("wingdi.h", MSDNShortId = "5b241224-2994-4533-9629-d2a4b129ce86")] - [return: MarshalAs(UnmanagedType.Bool)] - public static extern bool DeleteColorSpace(HCOLORSPACE hcs); + /// Turns on color management. Turns off old-style color correction of halftones. + ICM_ON = 2, + + /// Queries the current state of color management. + ICM_QUERY = 3, /// - /// The EnumICMProfiles function enumerates the different output color profiles that the system supports for a given device context. + /// Turns off color management inside DC. Under Windows 2000, also turns off old-style color correction of halftones. Not + /// supported under Windows 95. /// - /// Specifies the device context. - /// Specifies the procedure instance address of a callback function defined by the application. (See EnumICMProfilesProcCallback.) - /// Data supplied by the application that is passed to the callback function along with the color profile information. - /// - /// This function returns zero if the application interrupted the enumeration. The return value is -1 if there are no color profiles - /// to enumerate. Otherwise, the return value is the last value returned by the callback function. - /// - /// - /// - /// The EnumICMProfiles function returns a list of profiles that are associated with a device context (DC), and whose settings - /// match those of the DC. It is possible for a device context to contain device profiles that are not associated with particular - /// hardware devices, or device profiles that do not match the settings of the DC. The sRGB profile is an example. The SetICMProfile - /// function is used to associate these types of profiles with a DC. The GetICMProfile function can be used to retrieve a profile - /// that is not enumerated by the EnumICMProfiles function. - /// - /// - /// Windows 95/98/Me:EnumICMProfilesW is supported by the Microsoft Layer for Unicode. To use this, you must add - /// certain files to your application, as outlined in Microsoft Layer for Unicode on Windows 95/98/Me Systems. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/wingdi/nf-wingdi-enumicmprofilesw int EnumICMProfilesW( HDC hdc, ICMENUMPROCW - // proc, LPARAM param ); - [DllImport(Lib.Gdi32, SetLastError = false, CharSet = CharSet.Auto)] - [PInvokeData("wingdi.h", MSDNShortId = "a93e6239-b6c7-4e37-9f06-03790a3ed53f")] - public static extern int EnumICMProfiles(HDC hdc, EnumICMProfilesProcCallback proc, [Optional] IntPtr param); + ICM_DONE_OUTSIDEDC = 4, + } - /// The GetColorAdjustment function retrieves the color adjustment values for the specified device context (DC). - /// A handle to the device context. - /// A pointer to a COLORADJUSTMENT structure that receives the color adjustment values. - /// - /// If the function succeeds, the return value is nonzero. - /// If the function fails, the return value is zero. - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/wingdi/nf-wingdi-getcoloradjustment BOOL GetColorAdjustment( HDC hdc, - // LPCOLORADJUSTMENT lpca ); - [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] - [PInvokeData("wingdi.h", MSDNShortId = "405c0d0d-9433-4f4a-9957-5c42a0fb3a07")] - [return: MarshalAs(UnmanagedType.Bool)] - public static extern bool GetColorAdjustment(HDC hdc, ref COLORADJUSTMENT lpca); + /// The type of standard light source under which the image is viewed. + [PInvokeData("wingdi.h", MSDNShortId = "9a080f60-0bce-46b6-b8a8-f534ff83a0a8")] + public enum ILLUMINANT : ushort + { + /// Device's default. Standard used by output devices. + ILLUMINANT_DEVICE_DEFAULT = 0, - /// The GetColorSpace function retrieves the handle to the input color space from a specified device context. - /// Specifies a device context that is to have its input color space handle retrieved. - /// - /// If the function succeeds, the return value is the current input color space handle. - /// If this function fails, the return value is NULL. - /// - /// - /// GetColorSpace obtains the handle to the input color space regardless of whether color management is enabled for the device context. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/wingdi/nf-wingdi-getcolorspace HCOLORSPACE GetColorSpace( HDC hdc ); - [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] - [PInvokeData("wingdi.h", MSDNShortId = "6d092755-2c7a-46a7-9127-df72c26c3ae9")] - public static extern HCOLORSPACE GetColorSpace(HDC hdc); + /// Tungsten lamp. + ILLUMINANT_A = 1, - /// The GetDeviceGammaRamp function gets the gamma ramp on direct color display boards having drivers that support downloadable gamma ramps in hardware. - /// Specifies the device context of the direct color display board in question. - /// Points to a buffer where the function can place the current gamma ramp of the color display board. The gamma ramp is specified in three arrays of 256 WORD elements each, which contain the mapping between RGB values in the frame buffer and digital-analog-converter (DAC) values. The sequence of the arrays is red, green, blue. - /// - /// If this function succeeds, the return value is TRUE. - /// If this function fails, the return value is FALSE. - /// - /// Direct color display modes do not use color lookup tables and are usually 16, 24, or 32 bit. Not all direct color video boards support loadable gamma ramps. GetDeviceGammaRamp succeeds only for devices with drivers that support downloadable gamma ramps in hardware. - // https://docs.microsoft.com/en-us/windows/win32/api/wingdi/nf-wingdi-getdevicegammaramp - // BOOL GetDeviceGammaRamp( HDC hdc, LPVOID lpRamp ); - [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] - [PInvokeData("wingdi.h", MSDNShortId = "c32600a9-545e-4bbf-a3c1-21878f5106b0")] - [return: MarshalAs(UnmanagedType.Bool)] - public static extern bool GetDeviceGammaRamp(HDC hdc, IntPtr lpRamp); + /// Noon sunlight. + ILLUMINANT_B = 2, + + /// NTSC daylight. + ILLUMINANT_C = 3, + + /// Normal print. + ILLUMINANT_D50 = 4, + + /// Bond paper print. + ILLUMINANT_D55 = 5, + + /// Standard daylight. Standard for CRTs and pictures. + ILLUMINANT_D65 = 6, + + /// Northern daylight. + ILLUMINANT_D75 = 7, + + /// Cool white lamp. + ILLUMINANT_F2 = 8, + + /// Same as ILLUMINANT_A. + ILLUMINANT_TUNGSTEN = ILLUMINANT_A, + + /// Same as ILLUMINANT_C. + ILLUMINANT_DAYLIGHT = ILLUMINANT_C, + + /// Same as ILLUMINANT_F2. + ILLUMINANT_FLUORESCENT = ILLUMINANT_F2, + + /// Same as ILLUMINANT_C. + ILLUMINANT_NTSC = ILLUMINANT_C, + } + + /// Color space type. + [PInvokeData("wingdi.h", MSDNShortId = "b08aec07-6ac0-47be-8dc9-d604d94dedde")] + public enum LCSCSTYPE : uint + { + /// + /// Color values are calibrated RGB values. The values are translated using the endpoints specified by the lcsEndpoints member + /// before being passed to the device. + /// + LCS_CALIBRATED_RGB = 0, + + /// Color values are values are sRGB values. + LCS_sRGB = 0x73524742, + + /// Color values are Windows default color space color values. + LCS_WINDOWS_COLOR_SPACE = 0x57696e20, + } + + /// The gamut mapping method. + [PInvokeData("wingdi.h", MSDNShortId = "b08aec07-6ac0-47be-8dc9-d604d94dedde")] + [Flags] + public enum LCSGAMUTMATCH : uint + { + /// Maintain saturation. Used for business charts and other situations in which undithered colors are required. + LCS_GM_BUSINESS = 0x00000001, + + /// Maintain colorimetric match. Used for graphic designs and named colors. + LCS_GM_GRAPHICS = 0x00000002, + + /// Maintain contrast. Used for photographs and natural images. + LCS_GM_IMAGES = 0x00000004, + + /// Maintain the white point. Match the colors to their nearest color in the destination gamut. + LCS_GM_ABS_COLORIMETRIC = 0x00000008, + } + + /// The current state of the system (physical) palette. + [PInvokeData("wingdi.h", MSDNShortId = "0a9e7906-2f81-4fda-b03d-86feb0755327")] + public enum SYSPAL + { + /// The given device context is invalid or does not support a color palette. + SYSPAL_ERROR = 0, + + /// The system palette contains static colors that will not change when an application realizes its logical palette. + SYSPAL_STATIC = 1, + + /// The system palette contains no static colors except black and white. + SYSPAL_NOSTATIC = 2, + + /// The system palette contains no static colors. + SYSPAL_NOSTATIC256 = 3, + } + + /// The AnimatePalette function replaces entries in the specified logical palette. + /// A handle to the logical palette. + /// The first logical palette entry to be replaced. + /// The number of entries to be replaced. + /// A pointer to the first member in an array of PALETTEENTRY structures used to replace the current entries. + /// + /// If the function succeeds, the return value is nonzero. + /// If the function fails, the return value is zero. + /// + /// + /// + /// An application can determine whether a device supports palette operations by calling the GetDeviceCaps function and specifying + /// the RASTERCAPS constant. + /// + /// + /// The AnimatePalette function only changes entries with the PC_RESERVED flag set in the corresponding palPalEntry + /// member of the LOGPALETTE structure. + /// + /// If the given palette is associated with the active window, the colors in the palette are replaced immediately. + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/wingdi/nf-wingdi-animatepalette BOOL AnimatePalette( HPALETTE hPal, UINT + // iStartIndex, UINT cEntries, const PALETTEENTRY *ppe ); + [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] + [PInvokeData("wingdi.h", MSDNShortId = "65dd45e2-39a4-4a94-bd14-b0c8e4a609a3")] + [return: MarshalAs(UnmanagedType.Bool)] + public static extern bool AnimatePalette(HPALETTE hPal, uint iStartIndex, uint cEntries, [In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 2)] PALETTEENTRY[] ppe); + + /// + /// The CheckColorsInGamut function determines whether a specified set of RGB triples lies in the output gamut of a specified + /// device. The RGB triples are interpreted in the input logical color space. + /// + /// Handle to the device context whose output gamut to be checked. + /// Pointer to an array of RGB triples to check. + /// + /// Pointer to the buffer in which the results are to be placed. This buffer must be at least as large as nCount bytes. + /// + /// The number of elements in the array of triples. + /// + /// If this function succeeds, the return value is a nonzero value. + /// If this function fails, the return value is zero. + /// + /// + /// + /// The function places the test results in the buffer pointed to by lpBuffer. Each byte in the buffer corresponds to an RGB triple, + /// and has an unsigned value between CM_IN_GAMUT (= 0) and CM_OUT_OF_GAMUT (= 255). The value 0 denotes that the color is in gamut, + /// while a nonzero value denotes that it is out of gamut. For any integer n such that 0 < n < 255, a result value of n + 1 + /// indicates that the corresponding color is at least as far out of gamut as would be indicated by a result value of n, as specified + /// by the ICC Profile Format Specification. For more information on the ICC Profile Format Specification, see the sources listed in + /// Further Information. + /// + /// + /// Note that for this function to succeed, WCS must be enabled for the device context handle that is passed in through the hDC + /// parameter. WCS can be enabled for a device context handle by calling the SetICMMode function. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/wingdi/nf-wingdi-checkcolorsingamut BOOL CheckColorsInGamut( HDC hdc, + // LPRGBTRIPLE lpRGBTriple, LPVOID dlpBuffer, DWORD nCount ); + [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] + [PInvokeData("wingdi.h", MSDNShortId = "87bee1a6-e3dd-4d0b-ad8a-9584833d9463")] + [return: MarshalAs(UnmanagedType.Bool)] + public static extern bool CheckColorsInGamut(HDC hdc, [In] RGBTRIPLE[] lpRGBTriple, IntPtr dlpBuffer, uint nCount); + + /// + /// The ColorCorrectPalette function corrects the entries of a palette using the WCS 1.0 parameters in the specified device context. + /// + /// Specifies a device context whose WCS parameters to use. + /// Specifies the handle to the palette to be color corrected. + /// Specifies the first entry in the palette to be color corrected. + /// Specifies the number of entries to color correct. + /// + /// If this function succeeds, the return value is TRUE. + /// If this function fails, the return value is FALSE. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/wingdi/nf-wingdi-colorcorrectpalette BOOL ColorCorrectPalette( HDC hdc, + // HPALETTE hPal, DWORD deFirst, DWORD num ); + [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] + [PInvokeData("wingdi.h", MSDNShortId = "e7680521-fb1e-4292-945f-867964dac1ab")] + [return: MarshalAs(UnmanagedType.Bool)] + public static extern bool ColorCorrectPalette(HDC hdc, HPALETTE hPal, uint deFirst, uint num); + + /// The ColorMatchToTarget function enables you to preview colors as they would appear on the target device. + /// Specifies the device context for previewing, generally the screen. + /// Specifies the target device context, generally a printer. + /// + /// A constant that can have one of the following values. + /// + /// + /// Value + /// Meaning + /// + /// + /// CS_ENABLE + /// + /// Map the colors to the target device's color gamut. This enables color proofing. All subsequent draw commands to the DC will + /// render colors as they would appear on the target device. + /// + /// + /// + /// CS_DISABLE + /// Disable color proofing. + /// + /// + /// CS_DELETE_TRANSFORM + /// If color management is enabled for the target profile, disable it and delete the concatenated transform. + /// + /// + /// + /// + /// If this function succeeds, the return value is TRUE. + /// If this function fails, the return value is FALSE. + /// + /// + /// + /// ColorMatchToTarget can be used to proof the colors of a color output device on another color output device. Setting the + /// uiAction parameter to CS_ENABLE causes all subsequent drawing commands to the DC to render colors as they would appear on the + /// target device. If uiAction is set to CS_DISABLE, proofing is turned off. However, the current color transform is not deleted from + /// the DC. It is just inactive. + /// + /// + /// When ColorMatchToTarget is called, the color transform for the target device is performed first, and then the transform to + /// the preview device is applied to the results of the first transform. This is used primarily for checking gamut mapping + /// conditions. Before using this function, you must enable WCS for both device contexts. + /// + /// + /// This function cannot be cascaded. While color mapping to the target is enabled by setting uiAction to CS_ENABLE, application + /// changes to the color space or gamut mapping method are ignored. Those changes then take effect when color mapping to the target + /// is disabled. + /// + /// + /// Note A memory leak will not occur if an application does not delete a transform using CS_DELETE_TRANSFORM. The transform + /// will be deleted when either the device context (DC) is closed, or when the application color space is deleted. However if the + /// transform is not going to be used again, or if the application will not be performing any more color matching on the DC, it + /// should explicitly delete the transform to free the memory it occupies. + /// + /// + /// The uiAction parameter should only be set to CS_DELETE_TRANSFORM if color management is enabled before the + /// ColorMatchToTarget function is called. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/wingdi/nf-wingdi-colormatchtotarget BOOL ColorMatchToTarget( HDC hdc, HDC + // hdcTarget, DWORD action ); + [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] + [PInvokeData("wingdi.h", MSDNShortId = "eb922411-0808-4404-bdaf-bf29d0cad379")] + [return: MarshalAs(UnmanagedType.Bool)] + public static extern bool ColorMatchToTarget(HDC hdc, HDC hdcTarget, CS action); + + /// The CreateColorSpace function creates a logical color space. + /// Pointer to the LOGCOLORSPACE data structure. + /// + /// If this function succeeds, the return value is a handle that identifies a color space. + /// If this function fails, the return value is NULL. + /// + /// + /// When the color space is no longer needed, use DeleteColorSpace to delete it. + /// + /// Windows 95/98/Me:CreateColorSpaceW is supported by the Microsoft Layer for Unicode. To use this, you must add + /// certain files to your application, as outlined in Microsoft Layer for Unicode on Windows 95/98/Me Systems. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/wingdi/nf-wingdi-createcolorspacea HCOLORSPACE CreateColorSpaceA( + // LPLOGCOLORSPACEA lplcs ); + [DllImport(Lib.Gdi32, SetLastError = false, CharSet = CharSet.Auto)] + [PInvokeData("wingdi.h", MSDNShortId = "c3fc798c-4bb9-4010-87d4-edc0005b7698")] + public static extern SafeHCOLORSPACE CreateColorSpace(in LOGCOLORSPACE lplcs); + + /// The CreateHalftonePalette function creates a halftone palette for the specified device context (DC). + /// A handle to the device context. + /// + /// If the function succeeds, the return value is a handle to a logical halftone palette. + /// If the function fails, the return value is zero. + /// + /// + /// + /// An application should create a halftone palette when the stretching mode of a device context is set to HALFTONE. The logical + /// halftone palette returned by CreateHalftonePalette should then be selected and realized into the device context before the + /// StretchBlt or StretchDIBits function is called. + /// + /// When you no longer need the palette, call the DeleteObject function to delete it. + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/wingdi/nf-wingdi-createhalftonepalette HPALETTE CreateHalftonePalette( HDC + // hdc ); + [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] + [PInvokeData("wingdi.h", MSDNShortId = "ba9dfa0c-98df-4922-acba-d00e9b4b0fb0")] + public static extern SafeHPALETTE CreateHalftonePalette(HDC hdc); + + /// The CreatePalette function creates a logical palette. + /// A pointer to a LOGPALETTE structure that contains information about the colors in the logical palette. + /// + /// If the function succeeds, the return value is a handle to a logical palette. + /// If the function fails, the return value is NULL. + /// + /// + /// + /// An application can determine whether a device supports palette operations by calling the GetDeviceCaps function and specifying + /// the RASTERCAPS constant. + /// + /// + /// Once an application creates a logical palette, it can select that palette into a device context by calling the SelectPalette + /// function. A palette selected into a device context can be realized by calling the RealizePalette function. + /// + /// When you no longer need the palette, call the DeleteObject function to delete it. + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/wingdi/nf-wingdi-createpalette HPALETTE CreatePalette( const LOGPALETTE + // *plpal ); + [PInvokeData("wingdi.h", MSDNShortId = "f3462198-9360-4b77-ac62-9fe21ec666be")] + [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] + public static extern SafeHPALETTE CreatePalette([In, MarshalAs(UnmanagedType.CustomMarshaler, MarshalTypeRef = typeof(VanaraCustomMarshaler))] LOGPALETTE plpal); + + /// The DeleteColorSpace function removes and destroys a specified color space. + /// Specifies the handle to a color space to delete. + /// + /// If this function succeeds, the return value is TRUE. + /// If this function fails, the return value is FALSE. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/wingdi/nf-wingdi-deletecolorspace BOOL DeleteColorSpace( HCOLORSPACE hcs ); + [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] + [PInvokeData("wingdi.h", MSDNShortId = "5b241224-2994-4533-9629-d2a4b129ce86")] + [return: MarshalAs(UnmanagedType.Bool)] + public static extern bool DeleteColorSpace(HCOLORSPACE hcs); + + /// + /// The EnumICMProfiles function enumerates the different output color profiles that the system supports for a given device context. + /// + /// Specifies the device context. + /// Specifies the procedure instance address of a callback function defined by the application. (See EnumICMProfilesProcCallback.) + /// Data supplied by the application that is passed to the callback function along with the color profile information. + /// + /// This function returns zero if the application interrupted the enumeration. The return value is -1 if there are no color profiles + /// to enumerate. Otherwise, the return value is the last value returned by the callback function. + /// + /// + /// + /// The EnumICMProfiles function returns a list of profiles that are associated with a device context (DC), and whose settings + /// match those of the DC. It is possible for a device context to contain device profiles that are not associated with particular + /// hardware devices, or device profiles that do not match the settings of the DC. The sRGB profile is an example. The SetICMProfile + /// function is used to associate these types of profiles with a DC. The GetICMProfile function can be used to retrieve a profile + /// that is not enumerated by the EnumICMProfiles function. + /// + /// + /// Windows 95/98/Me:EnumICMProfilesW is supported by the Microsoft Layer for Unicode. To use this, you must add + /// certain files to your application, as outlined in Microsoft Layer for Unicode on Windows 95/98/Me Systems. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/wingdi/nf-wingdi-enumicmprofilesw int EnumICMProfilesW( HDC hdc, ICMENUMPROCW + // proc, LPARAM param ); + [DllImport(Lib.Gdi32, SetLastError = false, CharSet = CharSet.Auto)] + [PInvokeData("wingdi.h", MSDNShortId = "a93e6239-b6c7-4e37-9f06-03790a3ed53f")] + public static extern int EnumICMProfiles(HDC hdc, EnumICMProfilesProcCallback proc, [Optional] IntPtr param); + + /// The GetColorAdjustment function retrieves the color adjustment values for the specified device context (DC). + /// A handle to the device context. + /// A pointer to a COLORADJUSTMENT structure that receives the color adjustment values. + /// + /// If the function succeeds, the return value is nonzero. + /// If the function fails, the return value is zero. + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/wingdi/nf-wingdi-getcoloradjustment BOOL GetColorAdjustment( HDC hdc, + // LPCOLORADJUSTMENT lpca ); + [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] + [PInvokeData("wingdi.h", MSDNShortId = "405c0d0d-9433-4f4a-9957-5c42a0fb3a07")] + [return: MarshalAs(UnmanagedType.Bool)] + public static extern bool GetColorAdjustment(HDC hdc, ref COLORADJUSTMENT lpca); + + /// The GetColorSpace function retrieves the handle to the input color space from a specified device context. + /// Specifies a device context that is to have its input color space handle retrieved. + /// + /// If the function succeeds, the return value is the current input color space handle. + /// If this function fails, the return value is NULL. + /// + /// + /// GetColorSpace obtains the handle to the input color space regardless of whether color management is enabled for the device context. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/wingdi/nf-wingdi-getcolorspace HCOLORSPACE GetColorSpace( HDC hdc ); + [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] + [PInvokeData("wingdi.h", MSDNShortId = "6d092755-2c7a-46a7-9127-df72c26c3ae9")] + public static extern HCOLORSPACE GetColorSpace(HDC hdc); + + /// The GetDeviceGammaRamp function gets the gamma ramp on direct color display boards having drivers that support downloadable gamma ramps in hardware. + /// Specifies the device context of the direct color display board in question. + /// Points to a buffer where the function can place the current gamma ramp of the color display board. The gamma ramp is specified in three arrays of 256 WORD elements each, which contain the mapping between RGB values in the frame buffer and digital-analog-converter (DAC) values. The sequence of the arrays is red, green, blue. + /// + /// If this function succeeds, the return value is TRUE. + /// If this function fails, the return value is FALSE. + /// + /// Direct color display modes do not use color lookup tables and are usually 16, 24, or 32 bit. Not all direct color video boards support loadable gamma ramps. GetDeviceGammaRamp succeeds only for devices with drivers that support downloadable gamma ramps in hardware. + // https://docs.microsoft.com/en-us/windows/win32/api/wingdi/nf-wingdi-getdevicegammaramp + // BOOL GetDeviceGammaRamp( HDC hdc, LPVOID lpRamp ); + [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] + [PInvokeData("wingdi.h", MSDNShortId = "c32600a9-545e-4bbf-a3c1-21878f5106b0")] + [return: MarshalAs(UnmanagedType.Bool)] + public static extern bool GetDeviceGammaRamp(HDC hdc, IntPtr lpRamp); + + /// + /// The GetICMProfile function retrieves the file name of the current output color profile for a specified device context. + /// + /// Specifies a device context from which to retrieve the color profile. + /// + /// Pointer to a DWORD that contains the size of the buffer pointed to by lpszFilename. For the ANSI version of this function, + /// the size is in bytes. For the Unicode version, the size is in WCHARs. If this function is successful, on return this parameter + /// contains the size of the buffer actually used. However, if the buffer is not large enough, this function returns FALSE. In + /// this case, the GetLastError() function returns ERROR_INSUFFICIENT_BUFFER and the DWORD pointed to by this parameter + /// contains the size needed for the lpszFilename buffer. + /// + /// Points to the buffer that receives the path name of the profile. + /// + /// + /// If this function succeeds, the return value is TRUE. It also returns TRUE if the lpszFilename parameter is + /// NULL and the size required for the buffer is copied into lpcbName. + /// + /// If this function fails, the return value is FALSE. + /// + /// + /// + /// GetICMProfile obtains the file name of the current output profile regardless of whether or not color management is enabled + /// for the device context. + /// + /// + /// Given a device context, GetICMProfile will output, through the parameter lpszFilename, the path name of the file + /// containing the color profile currently being used by the device context. It will also output, through the parameter lpcbName, the + /// length of the string containing the path name. + /// + /// + /// It is possible that the profile name returned by GetICMProfile will not be in the list of profiles returned by + /// EnumICMProfiles. The EnumICMProfiles function returns all color space profiles that are associated with a device context + /// (DC) whose settings match that of the DC. If the SetICMProfile function is used to set the current profile, a profile may be + /// associated with the DC that does not match its settings. For instance, the SetICMProfile function can be used to associate + /// the device-independent sRGB profile with a DC. This profile will be used as the current WCS profile for that DC, and calls to + /// GetICMProfile will return its file name. However, the profile will not appear in the list of profiles that is returned + /// from EnumICMProfiles. + /// + /// + /// If this function is called before any calls to the SetICMProfile function, it can be used to get the default profile for a + /// device context. + /// + /// + /// Windows 95/98/Me:GetICMProfileW is supported by the Microsoft Layer for Unicode. To use this, you must add certain + /// files to your application, as outlined in Microsoft Layer for Unicode on Windows 95/98/Me Systems. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/wingdi/nf-wingdi-geticmprofilea BOOL GetICMProfileA( HDC hdc, LPDWORD pBufSize, + // LPSTR pszFilename ); + [DllImport(Lib.Gdi32, SetLastError = true, CharSet = CharSet.Auto)] + [PInvokeData("wingdi.h", MSDNShortId = "1e16771a-80c5-47bb-9c98-14169d4dd773")] + [return: MarshalAs(UnmanagedType.Bool)] + public static extern bool GetICMProfile(HDC hdc, ref uint pBufSize, StringBuilder pszFilename); + + /// The GetLogColorSpace function retrieves the color space definition identified by a specified handle. + /// Specifies the handle to a color space. + /// Points to a buffer to receive the LOGCOLORSPACE structure. + /// Specifies the maximum size of the buffer. + /// + /// If this function succeeds, the return value is TRUE. + /// If this function fails, the return value is FALSE. + /// + /// + /// Windows 95/98/Me:GetLogColorSpaceW is supported by the Microsoft Layer for Unicode. To use this, you must add + /// certain files to your application, as outlined in Microsoft Layer for Unicode on Windows 95/98/Me Systems. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/wingdi/nf-wingdi-getlogcolorspacea BOOL GetLogColorSpaceA( HCOLORSPACE + // hColorSpace, LPLOGCOLORSPACEA lpBuffer, DWORD nSize ); + [DllImport(Lib.Gdi32, SetLastError = false, CharSet = CharSet.Auto)] + [PInvokeData("wingdi.h", MSDNShortId = "01862a48-8c2f-4b29-b928-2800c02218a2")] + [return: MarshalAs(UnmanagedType.Bool)] + public static extern bool GetLogColorSpace(HCOLORSPACE hColorSpace, ref LOGCOLORSPACE lpBuffer, uint nSize); + + /// + /// The GetNearestColor function retrieves a color value identifying a color from the system palette that will be displayed + /// when the specified color value is used. + /// + /// A handle to the device context. + /// A color value that identifies a requested color. To create a COLORREF color value, use the RGB macro. + /// + /// + /// If the function succeeds, the return value identifies a color from the system palette that corresponds to the given color value. + /// + /// If the function fails, the return value is CLR_INVALID. + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/wingdi/nf-wingdi-getnearestcolor COLORREF GetNearestColor( HDC hdc, COLORREF + // color ); + [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] + [PInvokeData("wingdi.h", MSDNShortId = "89e4e19b-47be-442e-8eb4-c867bb78f36a")] + public static extern COLORREF GetNearestColor(HDC hdc, COLORREF color); + + /// + /// The GetNearestPaletteIndex function retrieves the index for the entry in the specified logical palette most closely + /// matching a specified color value. + /// + /// + /// If the function succeeds, the return value is the index of an entry in a logical palette. + /// If the function fails, the return value is CLR_INVALID. + /// + /// + /// + /// An application can determine whether a device supports palette operations by calling the GetDeviceCaps function and + /// specifying the RASTERCAPS constant. + /// + /// If the given logical palette contains entries with the PC_EXPLICIT flag set, the return value is undefined. + /// + // https://docs.microsoft.com/en-us/previous-versions/dd144903(v%3dvs.85) UINT GetNearestPaletteIndex( _In_ HPALETTE hpal, _In_ + // COLORREF crColor ); + [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] + [PInvokeData("Wingdi.h")] + public static extern uint GetNearestPaletteIndex(HPALETTE hpal, COLORREF crColor); + + /// The GetPaletteEntries function retrieves a specified range of palette entries from the given logical palette. + /// A handle to the logical palette. + /// The first entry in the logical palette to be retrieved. + /// The number of entries in the logical palette to be retrieved. + /// + /// A pointer to an array of PALETTEENTRY structures to receive the palette entries. The array must contain at least as many + /// structures as specified by the nEntries parameter. + /// + /// + /// + /// If the function succeeds and the handle to the logical palette is a valid pointer (not NULL), the return value is the + /// number of entries retrieved from the logical palette. If the function succeeds and handle to the logical palette is NULL, + /// the return value is the number of entries in the given palette. + /// + /// If the function fails, the return value is zero. + /// + /// + /// + /// An application can determine whether a device supports palette operations by calling the GetDeviceCaps function and specifying + /// the RASTERCAPS constant. + /// + /// + /// If the nEntries parameter specifies more entries than exist in the palette, the remaining members of the PALETTEENTRY structure + /// are not altered. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/wingdi/nf-wingdi-getpaletteentries UINT GetPaletteEntries( HPALETTE hpal, + // UINT iStart, UINT cEntries, LPPALETTEENTRY pPalEntries ); + [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] + [PInvokeData("wingdi.h", MSDNShortId = "5e72e881-32e1-458e-a09e-91fa13abe178")] + public static extern uint GetPaletteEntries(HPALETTE hpal, uint iStart, uint cEntries, [Out, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 2)] PALETTEENTRY[] pPalEntries); + + /// + /// The GetSystemPaletteEntries function retrieves a range of palette entries from the system palette that is associated with + /// the specified device context (DC). + /// + /// A handle to the device context. + /// The first entry to be retrieved from the system palette. + /// The number of entries to be retrieved from the system palette. + /// + /// A pointer to an array of PALETTEENTRY structures to receive the palette entries. The array must contain at least as many + /// structures as specified by the nEntries parameter. If this parameter is NULL, the function returns the total number of + /// entries in the palette. + /// + /// + /// If the function succeeds, the return value is the number of entries retrieved from the palette. + /// If the function fails, the return value is zero. + /// + /// + /// An application can determine whether a device supports palette operations by calling the GetDeviceCaps function and specifying + /// the RASTERCAPS constant. + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/wingdi/nf-wingdi-getsystempaletteentries UINT GetSystemPaletteEntries( HDC + // hdc, UINT iStart, UINT cEntries, LPPALETTEENTRY pPalEntries ); + [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] + [PInvokeData("wingdi.h", MSDNShortId = "67bb0adf-ae7f-48d5-bc62-82ece45aeee6")] + public static extern uint GetSystemPaletteEntries(HDC hdc, uint iStart, uint cEntries, [Out, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 2)] PALETTEENTRY[] pPalEntries); + + /// + /// The GetSystemPaletteUse function retrieves the current state of the system (physical) palette for the specified device + /// context (DC). + /// + /// A handle to the device context. + /// + /// + /// If the function succeeds, the return value is the current state of the system palette. This parameter can be one of the following values. + /// + /// + /// + /// Value + /// Meaning + /// + /// + /// SYSPAL_NOSTATIC + /// The system palette contains no static colors except black and white. + /// + /// + /// SYSPAL_STATIC + /// The system palette contains static colors that will not change when an application realizes its logical palette. + /// + /// + /// SYSPAL_ERROR + /// The given device context is invalid or does not support a color palette. + /// + /// + /// + /// + /// + /// By default, the system palette contains 20 static colors that are not changed when an application realizes its logical palette. + /// An application can gain access to most of these colors by calling the SetSystemPaletteUse function. + /// + /// The device context identified by the hdc parameter must represent a device that supports color palettes. + /// + /// An application can determine whether a device supports color palettes by calling the GetDeviceCaps function and specifying the + /// RASTERCAPS constant. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/wingdi/nf-wingdi-getsystempaletteuse UINT GetSystemPaletteUse( HDC hdc ); + [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] + [PInvokeData("wingdi.h", MSDNShortId = "0a9e7906-2f81-4fda-b03d-86feb0755327")] + public static extern SYSPAL GetSystemPaletteUse(HDC hdc); + + /// The RealizePalette function maps palette entries from the current logical palette to the system palette. + /// A handle to the device context into which a logical palette has been selected. + /// + /// If the function succeeds, the return value is the number of entries in the logical palette mapped to the system palette. + /// If the function fails, the return value is GDI_ERROR. + /// + /// + /// + /// An application can determine whether a device supports palette operations by calling the GetDeviceCaps function and specifying + /// the RASTERCAPS constant. + /// + /// + /// The RealizePalette function modifies the palette for the device associated with the specified device context. If the + /// device context is a memory DC, the color table for the bitmap selected into the DC is modified. If the device context is a + /// display DC, the physical palette for that device is modified. + /// + /// + /// A logical palette is a buffer between color-intensive applications and the system, allowing these applications to use as many + /// colors as needed without interfering with colors displayed by other windows. + /// + /// + /// When an application's window has the focus and it calls the RealizePalette function, the system attempts to realize as + /// many of the requested colors as possible. The same is also true for applications with inactive windows. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/wingdi/nf-wingdi-realizepalette UINT RealizePalette( HDC hdc ); + [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] + [PInvokeData("wingdi.h", MSDNShortId = "1c744ad2-09bc-455f-bc3c-9a2583b57a30")] + public static extern uint RealizePalette(HDC hdc); + + /// The ResizePalette function increases or decreases the size of a logical palette based on the specified value. + /// A handle to the palette to be changed. + /// + /// The number of entries in the palette after it has been resized. + /// The number of entries is limited to 1024. + /// + /// + /// If the function succeeds, the return value is nonzero. + /// If the function fails, the return value is zero. + /// + /// + /// + /// An application can determine whether a device supports palette operations by calling the GetDeviceCaps function and specifying + /// the RASTERCAPS constant. + /// + /// + /// If an application calls ResizePalette to reduce the size of the palette, the entries remaining in the resized palette are + /// unchanged. If the application calls ResizePalette to enlarge the palette, the additional palette entries are set to black + /// (the red, green, and blue values are all 0) and their flags are set to zero. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/wingdi/nf-wingdi-resizepalette BOOL ResizePalette( HPALETTE hpal, UINT n ); + [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] + [PInvokeData("wingdi.h", MSDNShortId = "77178869-cbfb-4b91-a5b0-7d0404e7534f")] + [return: MarshalAs(UnmanagedType.Bool)] + public static extern bool ResizePalette(HPALETTE hpal, uint n); + + /// The SelectPalette function selects the specified logical palette into a device context. + /// A handle to the device context. + /// A handle to the logical palette to be selected. + /// + /// + /// Specifies whether the logical palette is forced to be a background palette. If this value is TRUE, the RealizePalette + /// function causes the logical palette to be mapped to the colors already in the physical palette in the best possible way. This is + /// always done, even if the window for which the palette is realized belongs to a thread without active focus. + /// + /// + /// If this value is FALSE, RealizePalette causes the logical palette to be copied into the device palette when the + /// application is in the foreground. (If the hdc parameter is a memory device context, this parameter is ignored.) + /// + /// + /// + /// If the function succeeds, the return value is a handle to the device context's previous logical palette. + /// If the function fails, the return value is NULL. + /// + /// + /// + /// An application can determine whether a device supports palette operations by calling the GetDeviceCaps function and specifying + /// the RASTERCAPS constant. + /// + /// + /// An application can select a logical palette into more than one device context only if device contexts are compatible. Otherwise + /// SelectPalette fails. To create a device context that is compatible with another device context, call CreateCompatibleDC + /// with the first device context as the parameter. If a logical palette is selected into more than one device context, changes to + /// the logical palette will affect all device contexts for which it is selected. + /// + /// + /// An application might call the SelectPalette function with the bForceBackground parameter set to TRUE if the child + /// windows of a top-level window each realize their own palettes. However, only the child window that needs to realize its palette + /// must set bForceBackground to TRUE; other child windows must set this value to FALSE. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/wingdi/nf-wingdi-selectpalette HPALETTE SelectPalette( HDC hdc, HPALETTE + // hPal, BOOL bForceBkgd ); + [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] + [PInvokeData("wingdi.h", MSDNShortId = "1fc3356f-6fa3-444f-b224-b953acd2394b")] + public static extern HPALETTE SelectPalette(HDC hdc, HPALETTE hPal, [MarshalAs(UnmanagedType.Bool)] bool bForceBkgd); + + /// + /// The SetColorAdjustment function sets the color adjustment values for a device context (DC) using the specified values. + /// + /// A handle to the device context. + /// A pointer to a COLORADJUSTMENT structure containing the color adjustment values. + /// + /// If the function succeeds, the return value is nonzero. + /// If the function fails, the return value is zero. + /// + /// + /// The color adjustment values are used to adjust the input color of the source bitmap for calls to the StretchBlt and StretchDIBits + /// functions when HALFTONE mode is set. + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/wingdi/nf-wingdi-setcoloradjustment BOOL SetColorAdjustment( HDC hdc, const + // COLORADJUSTMENT *lpca ); + [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] + [PInvokeData("wingdi.h", MSDNShortId = "292d6cdc-cafa-438a-9392-a9c22e7d44a5")] + [return: MarshalAs(UnmanagedType.Bool)] + public static extern bool SetColorAdjustment(HDC hdc, in COLORADJUSTMENT lpca); + + /// The SetColorSpace function defines the input color space for a given device context. + /// Specifies the handle to a device context. + /// Identifies handle to the color space to set. + /// + /// If this function succeeds, the return value is a handle to the hColorSpace being replaced. + /// If this function fails, the return value is NULL. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/wingdi/nf-wingdi-setcolorspace HCOLORSPACE SetColorSpace( HDC hdc, HCOLORSPACE + // hcs ); + [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] + [PInvokeData("wingdi.h", MSDNShortId = "037c864f-f8ec-4467-9236-74ea4493d743")] + public static extern HCOLORSPACE SetColorSpace(HDC hdc, HCOLORSPACE hcs); + + /// + /// The SetDeviceGammaRamp function sets the gamma ramp on direct color display boards having drivers that support + /// downloadable gamma ramps in hardware. + /// + /// Specifies the device context of the direct color display board in question. + /// + /// Pointer to a buffer containing the gamma ramp to be set. The gamma ramp is specified in three arrays of 256 WORD elements + /// each, which contain the mapping between RGB values in the frame buffer and digital-analog-converter (DAC ) values. The sequence + /// of the arrays is red, green, blue. The RGB values must be stored in the most significant bits of each WORD to increase DAC independence. + /// + /// + /// If this function succeeds, the return value is TRUE. + /// If this function fails, the return value is FALSE. + /// + /// + /// Direct color display modes do not use color lookup tables and are usually 16, 24, or 32 bit. Not all direct color video boards + /// support loadable gamma ramps. SetDeviceGammaRamp succeeds only for devices with drivers that support downloadable gamma + /// ramps in hardware. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/wingdi/nf-wingdi-setdevicegammaramp + // BOOL SetDeviceGammaRamp( HDC hdc, LPVOID lpRamp ); + [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] + [PInvokeData("wingdi.h", MSDNShortId = "8e4cc9a4-f292-47a1-a12a-43a479326ca7")] + [return: MarshalAs(UnmanagedType.Bool)] + public static extern bool SetDeviceGammaRamp(HDC hdc, IntPtr lpRamp); + + /// + /// The SetICMMode function causes Image Color Management to be enabled, disabled, or queried on a given device context (DC). + /// + /// Identifies handle to the device context. + /// + /// Turns on and off image color management. This parameter can take one of the following constant values. + /// + /// + /// Value + /// Meaning + /// + /// + /// ICM_ON + /// Turns on color management. Turns off old-style color correction of halftones. + /// + /// + /// ICM_OFF + /// Turns off color management. Turns on old-style color correction of halftones. + /// + /// + /// ICM_QUERY + /// Queries the current state of color management. + /// + /// + /// ICM_DONE_OUTSIDEDC + /// + /// Turns off color management inside DC. Under Windows 2000, also turns off old-style color correction of halftones. Not supported + /// under Windows 95. + /// + /// + /// + /// + /// + /// If this function succeeds, the return value is a nonzero value. + /// If this function fails, the return value is zero. + /// + /// If ICM_QUERY is specified and the function succeeds, the nonzero value returned is ICM_ON or ICM_OFF to indicate the current mode. + /// + /// + /// + /// If the system cannot find an ICC color profile to match the state of the device, SetICMMode fails and returns zero. + /// + /// Once WCS is enabled for a device context (DC), colors passed into the DC using most Win32 API functions are color matched. The + /// primary exceptions are BitBlt and StretchBlt. The assumption is that when performing a bit block transfer (blit) + /// from one DC to another, the two DCs are already compatible and need no color correction. If this is not the case, color + /// correction may be performed. Specifically, if a device independent bitmap (DIB) is used as the source for a blit, and the blit is + /// performed into a DC that has WCS enabled, color matching will be performed. If this is not what you want, turn WCS off for the + /// destination DC by calling SetICMMode before calling BitBlt or StretchBlt. + /// + /// + /// If the CreateCompatibleDC function is used to create a bitmap in a DC, it is possible for the bitmap to be color matched + /// twice, once when it is created and once when a blit is performed. The reason is that a bitmap in a DC created by the + /// CreateCompatibleDC function acquires the current brush, pens, and palette of the source DC. However, WCS will be disabled + /// by default for the new DC. If WCS is later enabled for the new DC by using the SetICMMode function, a color correction + /// will be done. To prevent double color corrections through the use of the CreateCompatibleDC function, use the + /// SetICMMode function to turn WCS off for the source DC before the CreateCompatibleDC function is called. + /// + /// + /// When a compatible DC is created from a printer's DC (see CreateCompatibleDC ), the default is for color matching to always + /// be performed if it is enabled for the printer's DC. The default color profile for the printer is used when a blit is performed + /// into the printer's DC using SetDIBitsToDevice or StretchDIBits. If this is not what you want, turn WCS off for the + /// printer's DC by calling SetICMMode before calling SetDIBitsToDevice or StretchDIBits. + /// + /// + /// Also, when printing to a printer's DC with WCS turned on, the SetICMMode function needs to be called after every call to + /// the StartPage function to turn back on WCS. The StartPage function calls the RestoreDC and SaveDC + /// functions, which result in WCS being turned off for the printer's DC. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/wingdi/nf-wingdi-seticmmode int SetICMMode( HDC hdc, int mode ); + [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] + [PInvokeData("wingdi.h", MSDNShortId = "40d70c1f-c580-43c4-b44b-6c9388e138fb")] + public static extern int SetICMMode(HDC hdc, ICM mode); + + /// + /// The SetICMProfile function sets a specified color profile as the output profile for a specified device context (DC). + /// + /// Specifies a device context in which to set the color profile. + /// Specifies the path name of the color profile to be set. + /// + /// If this function succeeds, the return value is TRUE. + /// If this function fails, the return value is FALSE. + /// + /// + /// + /// SetICMProfile associates a color profile with a device context. It becomes the output profile for that device context. The + /// color profile does not have to be associated with any particular device. Device-independent profiles such as sRGB can also be + /// used. If the color profile is not associated with a hardware device, it will be returned by GetICMProfile, but not by EnumICMProfiles. + /// + /// + /// Note that under Windows 95 or later, the PostScript device driver for printers assumes a CMYK color model. Therefore, all + /// PostScript printers must use a CMYK color profile. Windows 2000 does not have this limitation. + /// + /// SetICMProfile supports only RGB profiles in compatible DCs. + /// + /// Windows 95/98/Me:SetICMProfileW is supported by the Microsoft Layer for Unicode. To use this, you must add certain + /// files to your application, as outlined in Microsoft Layer for Unicode on Windows 95/98/Me Systems. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/wingdi/nf-wingdi-seticmprofilew BOOL SetICMProfileW( HDC hdc, LPWSTR lpFileName ); + [DllImport(Lib.Gdi32, SetLastError = false, CharSet = CharSet.Auto)] + [PInvokeData("wingdi.h", MSDNShortId = "c95f6536-9377-4766-9eb6-004a41bcf6c5")] + [return: MarshalAs(UnmanagedType.Bool)] + public static extern bool SetICMProfile(HDC hdc, string lpFileName); + + /// + /// The SetPaletteEntries function sets RGB (red, green, blue) color values and flags in a range of entries in a logical palette. + /// + /// A handle to the logical palette. + /// The first logical-palette entry to be set. + /// The number of logical-palette entries to be set. + /// + /// A pointer to the first member of an array of PALETTEENTRY structures containing the RGB values and flags. + /// + /// + /// If the function succeeds, the return value is the number of entries that were set in the logical palette. + /// If the function fails, the return value is zero. + /// + /// + /// + /// An application can determine whether a device supports palette operations by calling the GetDeviceCaps function and specifying + /// the RASTERCAPS constant. + /// + /// + /// Even if a logical palette has been selected and realized, changes to the palette do not affect the physical palette in the + /// surface. RealizePalette must be called again to set the new logical palette into the surface. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/wingdi/nf-wingdi-setpaletteentries UINT SetPaletteEntries( HPALETTE hpal, + // UINT iStart, UINT cEntries, const PALETTEENTRY *pPalEntries ); + [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] + [PInvokeData("wingdi.h", MSDNShortId = "df38f482-75ba-4800-8b26-92204c63255e")] + public static extern uint SetPaletteEntries(HPALETTE hpal, uint iStart, uint cEntries, [In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 2)] PALETTEENTRY[] pPalEntries); + + /// + /// The SetSystemPaletteUse function allows an application to specify whether the system palette contains 2 or 20 static + /// colors. The default system palette contains 20 static colors. (Static colors cannot be changed when an application realizes a + /// logical palette.) + /// + /// A handle to the device context. This device context must refer to a device that supports color palettes. + /// + /// The new use of the system palette. This parameter can be one of the following values. + /// + /// + /// Value + /// Meaning + /// + /// + /// SYSPAL_NOSTATIC + /// The system palette contains two static colors (black and white). + /// + /// + /// SYSPAL_NOSTATIC256 + /// The system palette contains no static colors. + /// + /// + /// SYSPAL_STATIC + /// The system palette contains static colors that will not change when an application realizes its logical palette. + /// + /// + /// + /// + /// + /// If the function succeeds, the return value is the previous system palette. It can be either SYSPAL_NOSTATIC, SYSPAL_NOSTATIC256, + /// or SYSPAL_STATIC. + /// + /// If the function fails, the return value is SYSPAL_ERROR. + /// + /// + /// + /// An application can determine whether a device supports palette operations by calling the GetDeviceCaps function and specifying + /// the RASTERCAPS constant. + /// + /// + /// When an application window moves to the foreground and the SYSPAL_NOSTATIC value is set, the application must call the + /// GetSysColor function to save the current system colors setting. It must also call SetSysColors to set reasonable values using + /// only black and white. When the application returns to the background or terminates, the previous system colors must be restored. + /// + /// If the function returns SYSPAL_ERROR, the specified device context is invalid or does not support color palettes. + /// An application must call this function only when its window is maximized and has the input focus. + /// + /// If an application calls SetSystemPaletteUse with uUsage set to SYSPAL_NOSTATIC, the system continues to set aside two + /// entries in the system palette for pure white and pure black, respectively. + /// + /// After calling this function with uUsage set to SYSPAL_NOSTATIC, an application must take the following steps: + /// + /// + /// Realize the logical palette. + /// + /// + /// Call the GetSysColor function to save the current system-color settings. + /// + /// + /// + /// Call the SetSysColors function to set the system colors to reasonable values using black and white. For example, adjacent or + /// overlapping items (such as window frames and borders) should be set to black and white, respectively. + /// + /// + /// + /// Send the WM_SYSCOLORCHANGE message to other top-level windows to allow them to be redrawn with the new system colors. + /// + /// + /// When the application's window loses focus or closes, the application must perform the following steps: + /// + /// + /// Call SetSystemPaletteUse with the uUsage parameter set to SYSPAL_STATIC. + /// + /// + /// Realize the logical palette. + /// + /// + /// Restore the system colors to their previous values. + /// + /// + /// Send the WM_SYSCOLORCHANGE message. + /// + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/wingdi/nf-wingdi-setsystempaletteuse UINT SetSystemPaletteUse( HDC hdc, UINT + // use ); + [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] + [PInvokeData("wingdi.h", MSDNShortId = "6ff245d3-1bcc-4778-a595-c1eb16531ad3")] + public static extern SYSPAL SetSystemPaletteUse(HDC hdc, SYSPAL use); + + /// + /// The UnrealizeObject function resets the origin of a brush or resets a logical palette. If the hgdiobj parameter is a + /// handle to a brush, UnrealizeObject directs the system to reset the origin of the brush the next time it is selected. If + /// the hgdiobj parameter is a handle to a logical palette, UnrealizeObject directs the system to realize the palette as + /// though it had not previously been realized. The next time the application calls the RealizePalette function for the specified + /// palette, the system completely remaps the logical palette to the system palette. + /// + /// A handle to the logical palette to be reset. + /// + /// If the function succeeds, the return value is nonzero. + /// If the function fails, the return value is zero. + /// + /// + /// + /// The UnrealizeObject function should not be used with stock objects. For example, the default palette, obtained by calling + /// GetStockObject (DEFAULT_PALETTE), is a stock object. + /// + /// A palette identified by hgdiobj can be the currently selected palette of a device context. + /// + /// If hgdiobj is a brush, UnrealizeObject does nothing, and the function returns TRUE. Use SetBrushOrgEx to set the + /// origin of a brush. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/wingdi/nf-wingdi-unrealizeobject BOOL UnrealizeObject( HGDIOBJ h ); + [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] + [PInvokeData("wingdi.h", MSDNShortId = "b84cd0b3-fdf1-4f12-bc45-308032d6d698")] + [return: MarshalAs(UnmanagedType.Bool)] + public static extern bool UnrealizeObject(HGDIOBJ h); + + /// + /// The UpdateColors function updates the client area of the specified device context by remapping the current colors in the + /// client area to the currently realized logical palette. + /// + /// A handle to the device context. + /// + /// If the function succeeds, the return value is nonzero. + /// If the function fails, the return value is zero. + /// + /// + /// + /// An application can determine whether a device supports palette operations by calling the GetDeviceCaps function and specifying + /// the RASTERCAPS constant. + /// + /// + /// An inactive window with a realized logical palette may call UpdateColors as an alternative to redrawing its client area + /// when the system palette changes. + /// + /// + /// The UpdateColors function typically updates a client area faster than redrawing the area. However, because + /// UpdateColors performs the color translation based on the color of each pixel before the system palette changed, each call + /// to this function results in the loss of some color accuracy. + /// + /// This function must be called soon after a WM_PALETTECHANGED message is received. + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/wingdi/nf-wingdi-updatecolors BOOL UpdateColors( HDC hdc ); + [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] + [PInvokeData("wingdi.h", MSDNShortId = "61dfd579-3fc9-4e0a-bfd9-d04c6f918fd8")] + [return: MarshalAs(UnmanagedType.Bool)] + public static extern bool UpdateColors(HDC hdc); + + /// The CIEXYZ structure contains the x,y, and z coordinates of a specific color in a specified color space. + // https://docs.microsoft.com/en-us/windows/win32/api/wingdi/ns-wingdi-ciexyz typedef struct tagCIEXYZ { FXPT2DOT30 ciexyzX; + // FXPT2DOT30 ciexyzY; FXPT2DOT30 ciexyzZ; } CIEXYZ; + [PInvokeData("wingdi.h", MSDNShortId = "3735c143-8eb3-4b91-a81e-5bc6bda1dfaa")] + [StructLayout(LayoutKind.Sequential)] + public struct CIEXYZ + { + /// The x coordinate in fix point (2.30). + public int ciexyzX; + + /// The y coordinate in fix point (2.30). + public int ciexyzY; + + /// The z coordinate in fix point (2.30). + public int ciexyzZ; + } + + /// + /// The CIEXYZTRIPLE structure contains the x,y, and z coordinates of the three colors that correspond to the red, green, and + /// blue endpoints for a specified logical color space. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/wingdi/ns-wingdi-ciexyztriple typedef struct tagICEXYZTRIPLE { CIEXYZ + // ciexyzRed; CIEXYZ ciexyzGreen; CIEXYZ ciexyzBlue; } CIEXYZTRIPLE; + [PInvokeData("wingdi.h", MSDNShortId = "cf4473b0-7e54-42d1-a013-2442a540daee")] + [StructLayout(LayoutKind.Sequential)] + public struct CIEXYZTRIPLE + { + /// The xyz coordinates of red endpoint. + public CIEXYZ ciexyzRed; + + /// The xyz coordinates of green endpoint. + public CIEXYZ ciexyzGreen; + + /// The xyz coordinates of blue endpoint. + public CIEXYZ ciexyzBlue; + } + + /// + /// The COLORADJUSTMENT structure defines the color adjustment values used by the StretchBlt and StretchDIBits functions when + /// the stretch mode is HALFTONE. You can set the color adjustment values by calling the SetColorAdjustment function. + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/wingdi/ns-wingdi-coloradjustment typedef struct tagCOLORADJUSTMENT { WORD + // caSize; WORD caFlags; WORD caIlluminantIndex; WORD caRedGamma; WORD caGreenGamma; WORD caBlueGamma; WORD caReferenceBlack; WORD + // caReferenceWhite; SHORT caContrast; SHORT caBrightness; SHORT caColorfulness; SHORT caRedGreenTint; } COLORADJUSTMENT, + // *PCOLORADJUSTMENT, *LPCOLORADJUSTMENT; + [PInvokeData("wingdi.h", MSDNShortId = "9a080f60-0bce-46b6-b8a8-f534ff83a0a8")] + [StructLayout(LayoutKind.Sequential)] + public struct COLORADJUSTMENT + { + /// The size, in bytes, of the structure. + public ushort caSize; /// - /// The GetICMProfile function retrieves the file name of the current output color profile for a specified device context. - /// - /// Specifies a device context from which to retrieve the color profile. - /// - /// Pointer to a DWORD that contains the size of the buffer pointed to by lpszFilename. For the ANSI version of this function, - /// the size is in bytes. For the Unicode version, the size is in WCHARs. If this function is successful, on return this parameter - /// contains the size of the buffer actually used. However, if the buffer is not large enough, this function returns FALSE. In - /// this case, the GetLastError() function returns ERROR_INSUFFICIENT_BUFFER and the DWORD pointed to by this parameter - /// contains the size needed for the lpszFilename buffer. - /// - /// Points to the buffer that receives the path name of the profile. - /// /// - /// If this function succeeds, the return value is TRUE. It also returns TRUE if the lpszFilename parameter is - /// NULL and the size required for the buffer is copied into lpcbName. - /// - /// If this function fails, the return value is FALSE. - /// - /// - /// - /// GetICMProfile obtains the file name of the current output profile regardless of whether or not color management is enabled - /// for the device context. - /// - /// - /// Given a device context, GetICMProfile will output, through the parameter lpszFilename, the path name of the file - /// containing the color profile currently being used by the device context. It will also output, through the parameter lpcbName, the - /// length of the string containing the path name. - /// - /// - /// It is possible that the profile name returned by GetICMProfile will not be in the list of profiles returned by - /// EnumICMProfiles. The EnumICMProfiles function returns all color space profiles that are associated with a device context - /// (DC) whose settings match that of the DC. If the SetICMProfile function is used to set the current profile, a profile may be - /// associated with the DC that does not match its settings. For instance, the SetICMProfile function can be used to associate - /// the device-independent sRGB profile with a DC. This profile will be used as the current WCS profile for that DC, and calls to - /// GetICMProfile will return its file name. However, the profile will not appear in the list of profiles that is returned - /// from EnumICMProfiles. - /// - /// - /// If this function is called before any calls to the SetICMProfile function, it can be used to get the default profile for a - /// device context. - /// - /// - /// Windows 95/98/Me:GetICMProfileW is supported by the Microsoft Layer for Unicode. To use this, you must add certain - /// files to your application, as outlined in Microsoft Layer for Unicode on Windows 95/98/Me Systems. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/wingdi/nf-wingdi-geticmprofilea BOOL GetICMProfileA( HDC hdc, LPDWORD pBufSize, - // LPSTR pszFilename ); - [DllImport(Lib.Gdi32, SetLastError = true, CharSet = CharSet.Auto)] - [PInvokeData("wingdi.h", MSDNShortId = "1e16771a-80c5-47bb-9c98-14169d4dd773")] - [return: MarshalAs(UnmanagedType.Bool)] - public static extern bool GetICMProfile(HDC hdc, ref uint pBufSize, StringBuilder pszFilename); - - /// The GetLogColorSpace function retrieves the color space definition identified by a specified handle. - /// Specifies the handle to a color space. - /// Points to a buffer to receive the LOGCOLORSPACE structure. - /// Specifies the maximum size of the buffer. - /// - /// If this function succeeds, the return value is TRUE. - /// If this function fails, the return value is FALSE. - /// - /// - /// Windows 95/98/Me:GetLogColorSpaceW is supported by the Microsoft Layer for Unicode. To use this, you must add - /// certain files to your application, as outlined in Microsoft Layer for Unicode on Windows 95/98/Me Systems. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/wingdi/nf-wingdi-getlogcolorspacea BOOL GetLogColorSpaceA( HCOLORSPACE - // hColorSpace, LPLOGCOLORSPACEA lpBuffer, DWORD nSize ); - [DllImport(Lib.Gdi32, SetLastError = false, CharSet = CharSet.Auto)] - [PInvokeData("wingdi.h", MSDNShortId = "01862a48-8c2f-4b29-b928-2800c02218a2")] - [return: MarshalAs(UnmanagedType.Bool)] - public static extern bool GetLogColorSpace(HCOLORSPACE hColorSpace, ref LOGCOLORSPACE lpBuffer, uint nSize); - - /// - /// The GetNearestColor function retrieves a color value identifying a color from the system palette that will be displayed - /// when the specified color value is used. - /// - /// A handle to the device context. - /// A color value that identifies a requested color. To create a COLORREF color value, use the RGB macro. - /// - /// - /// If the function succeeds, the return value identifies a color from the system palette that corresponds to the given color value. - /// - /// If the function fails, the return value is CLR_INVALID. - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/wingdi/nf-wingdi-getnearestcolor COLORREF GetNearestColor( HDC hdc, COLORREF - // color ); - [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] - [PInvokeData("wingdi.h", MSDNShortId = "89e4e19b-47be-442e-8eb4-c867bb78f36a")] - public static extern COLORREF GetNearestColor(HDC hdc, COLORREF color); - - /// - /// The GetNearestPaletteIndex function retrieves the index for the entry in the specified logical palette most closely - /// matching a specified color value. - /// - /// - /// If the function succeeds, the return value is the index of an entry in a logical palette. - /// If the function fails, the return value is CLR_INVALID. - /// - /// - /// - /// An application can determine whether a device supports palette operations by calling the GetDeviceCaps function and - /// specifying the RASTERCAPS constant. - /// - /// If the given logical palette contains entries with the PC_EXPLICIT flag set, the return value is undefined. - /// - // https://docs.microsoft.com/en-us/previous-versions/dd144903(v%3dvs.85) UINT GetNearestPaletteIndex( _In_ HPALETTE hpal, _In_ - // COLORREF crColor ); - [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] - [PInvokeData("Wingdi.h")] - public static extern uint GetNearestPaletteIndex(HPALETTE hpal, COLORREF crColor); - - /// The GetPaletteEntries function retrieves a specified range of palette entries from the given logical palette. - /// A handle to the logical palette. - /// The first entry in the logical palette to be retrieved. - /// The number of entries in the logical palette to be retrieved. - /// - /// A pointer to an array of PALETTEENTRY structures to receive the palette entries. The array must contain at least as many - /// structures as specified by the nEntries parameter. - /// - /// - /// - /// If the function succeeds and the handle to the logical palette is a valid pointer (not NULL), the return value is the - /// number of entries retrieved from the logical palette. If the function succeeds and handle to the logical palette is NULL, - /// the return value is the number of entries in the given palette. - /// - /// If the function fails, the return value is zero. - /// - /// - /// - /// An application can determine whether a device supports palette operations by calling the GetDeviceCaps function and specifying - /// the RASTERCAPS constant. - /// - /// - /// If the nEntries parameter specifies more entries than exist in the palette, the remaining members of the PALETTEENTRY structure - /// are not altered. - /// - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/wingdi/nf-wingdi-getpaletteentries UINT GetPaletteEntries( HPALETTE hpal, - // UINT iStart, UINT cEntries, LPPALETTEENTRY pPalEntries ); - [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] - [PInvokeData("wingdi.h", MSDNShortId = "5e72e881-32e1-458e-a09e-91fa13abe178")] - public static extern uint GetPaletteEntries(HPALETTE hpal, uint iStart, uint cEntries, [Out, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 2)] PALETTEENTRY[] pPalEntries); - - /// - /// The GetSystemPaletteEntries function retrieves a range of palette entries from the system palette that is associated with - /// the specified device context (DC). - /// - /// A handle to the device context. - /// The first entry to be retrieved from the system palette. - /// The number of entries to be retrieved from the system palette. - /// - /// A pointer to an array of PALETTEENTRY structures to receive the palette entries. The array must contain at least as many - /// structures as specified by the nEntries parameter. If this parameter is NULL, the function returns the total number of - /// entries in the palette. - /// - /// - /// If the function succeeds, the return value is the number of entries retrieved from the palette. - /// If the function fails, the return value is zero. - /// - /// - /// An application can determine whether a device supports palette operations by calling the GetDeviceCaps function and specifying - /// the RASTERCAPS constant. - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/wingdi/nf-wingdi-getsystempaletteentries UINT GetSystemPaletteEntries( HDC - // hdc, UINT iStart, UINT cEntries, LPPALETTEENTRY pPalEntries ); - [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] - [PInvokeData("wingdi.h", MSDNShortId = "67bb0adf-ae7f-48d5-bc62-82ece45aeee6")] - public static extern uint GetSystemPaletteEntries(HDC hdc, uint iStart, uint cEntries, [Out, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 2)] PALETTEENTRY[] pPalEntries); - - /// - /// The GetSystemPaletteUse function retrieves the current state of the system (physical) palette for the specified device - /// context (DC). - /// - /// A handle to the device context. - /// - /// - /// If the function succeeds, the return value is the current state of the system palette. This parameter can be one of the following values. + /// Specifies how the output image should be prepared. This member may be set to NULL or any combination of the following values. /// /// /// @@ -646,850 +1178,317 @@ namespace Vanara.PInvoke /// Meaning /// /// - /// SYSPAL_NOSTATIC - /// The system palette contains no static colors except black and white. + /// CA_NEGATIVE + /// Specifies that the negative of the original image should be displayed. /// /// - /// SYSPAL_STATIC - /// The system palette contains static colors that will not change when an application realizes its logical palette. - /// - /// - /// SYSPAL_ERROR - /// The given device context is invalid or does not support a color palette. - /// - /// - /// - /// - /// - /// By default, the system palette contains 20 static colors that are not changed when an application realizes its logical palette. - /// An application can gain access to most of these colors by calling the SetSystemPaletteUse function. - /// - /// The device context identified by the hdc parameter must represent a device that supports color palettes. - /// - /// An application can determine whether a device supports color palettes by calling the GetDeviceCaps function and specifying the - /// RASTERCAPS constant. - /// - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/wingdi/nf-wingdi-getsystempaletteuse UINT GetSystemPaletteUse( HDC hdc ); - [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] - [PInvokeData("wingdi.h", MSDNShortId = "0a9e7906-2f81-4fda-b03d-86feb0755327")] - public static extern SYSPAL GetSystemPaletteUse(HDC hdc); - - /// The RealizePalette function maps palette entries from the current logical palette to the system palette. - /// A handle to the device context into which a logical palette has been selected. - /// - /// If the function succeeds, the return value is the number of entries in the logical palette mapped to the system palette. - /// If the function fails, the return value is GDI_ERROR. - /// - /// - /// - /// An application can determine whether a device supports palette operations by calling the GetDeviceCaps function and specifying - /// the RASTERCAPS constant. - /// - /// - /// The RealizePalette function modifies the palette for the device associated with the specified device context. If the - /// device context is a memory DC, the color table for the bitmap selected into the DC is modified. If the device context is a - /// display DC, the physical palette for that device is modified. - /// - /// - /// A logical palette is a buffer between color-intensive applications and the system, allowing these applications to use as many - /// colors as needed without interfering with colors displayed by other windows. - /// - /// - /// When an application's window has the focus and it calls the RealizePalette function, the system attempts to realize as - /// many of the requested colors as possible. The same is also true for applications with inactive windows. - /// - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/wingdi/nf-wingdi-realizepalette UINT RealizePalette( HDC hdc ); - [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] - [PInvokeData("wingdi.h", MSDNShortId = "1c744ad2-09bc-455f-bc3c-9a2583b57a30")] - public static extern uint RealizePalette(HDC hdc); - - /// The ResizePalette function increases or decreases the size of a logical palette based on the specified value. - /// A handle to the palette to be changed. - /// - /// The number of entries in the palette after it has been resized. - /// The number of entries is limited to 1024. - /// - /// - /// If the function succeeds, the return value is nonzero. - /// If the function fails, the return value is zero. - /// - /// - /// - /// An application can determine whether a device supports palette operations by calling the GetDeviceCaps function and specifying - /// the RASTERCAPS constant. - /// - /// - /// If an application calls ResizePalette to reduce the size of the palette, the entries remaining in the resized palette are - /// unchanged. If the application calls ResizePalette to enlarge the palette, the additional palette entries are set to black - /// (the red, green, and blue values are all 0) and their flags are set to zero. - /// - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/wingdi/nf-wingdi-resizepalette BOOL ResizePalette( HPALETTE hpal, UINT n ); - [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] - [PInvokeData("wingdi.h", MSDNShortId = "77178869-cbfb-4b91-a5b0-7d0404e7534f")] - [return: MarshalAs(UnmanagedType.Bool)] - public static extern bool ResizePalette(HPALETTE hpal, uint n); - - /// The SelectPalette function selects the specified logical palette into a device context. - /// A handle to the device context. - /// A handle to the logical palette to be selected. - /// - /// - /// Specifies whether the logical palette is forced to be a background palette. If this value is TRUE, the RealizePalette - /// function causes the logical palette to be mapped to the colors already in the physical palette in the best possible way. This is - /// always done, even if the window for which the palette is realized belongs to a thread without active focus. - /// - /// - /// If this value is FALSE, RealizePalette causes the logical palette to be copied into the device palette when the - /// application is in the foreground. (If the hdc parameter is a memory device context, this parameter is ignored.) - /// - /// - /// - /// If the function succeeds, the return value is a handle to the device context's previous logical palette. - /// If the function fails, the return value is NULL. - /// - /// - /// - /// An application can determine whether a device supports palette operations by calling the GetDeviceCaps function and specifying - /// the RASTERCAPS constant. - /// - /// - /// An application can select a logical palette into more than one device context only if device contexts are compatible. Otherwise - /// SelectPalette fails. To create a device context that is compatible with another device context, call CreateCompatibleDC - /// with the first device context as the parameter. If a logical palette is selected into more than one device context, changes to - /// the logical palette will affect all device contexts for which it is selected. - /// - /// - /// An application might call the SelectPalette function with the bForceBackground parameter set to TRUE if the child - /// windows of a top-level window each realize their own palettes. However, only the child window that needs to realize its palette - /// must set bForceBackground to TRUE; other child windows must set this value to FALSE. - /// - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/wingdi/nf-wingdi-selectpalette HPALETTE SelectPalette( HDC hdc, HPALETTE - // hPal, BOOL bForceBkgd ); - [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] - [PInvokeData("wingdi.h", MSDNShortId = "1fc3356f-6fa3-444f-b224-b953acd2394b")] - public static extern HPALETTE SelectPalette(HDC hdc, HPALETTE hPal, [MarshalAs(UnmanagedType.Bool)] bool bForceBkgd); - - /// - /// The SetColorAdjustment function sets the color adjustment values for a device context (DC) using the specified values. - /// - /// A handle to the device context. - /// A pointer to a COLORADJUSTMENT structure containing the color adjustment values. - /// - /// If the function succeeds, the return value is nonzero. - /// If the function fails, the return value is zero. - /// - /// - /// The color adjustment values are used to adjust the input color of the source bitmap for calls to the StretchBlt and StretchDIBits - /// functions when HALFTONE mode is set. - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/wingdi/nf-wingdi-setcoloradjustment BOOL SetColorAdjustment( HDC hdc, const - // COLORADJUSTMENT *lpca ); - [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] - [PInvokeData("wingdi.h", MSDNShortId = "292d6cdc-cafa-438a-9392-a9c22e7d44a5")] - [return: MarshalAs(UnmanagedType.Bool)] - public static extern bool SetColorAdjustment(HDC hdc, in COLORADJUSTMENT lpca); - - /// The SetColorSpace function defines the input color space for a given device context. - /// Specifies the handle to a device context. - /// Identifies handle to the color space to set. - /// - /// If this function succeeds, the return value is a handle to the hColorSpace being replaced. - /// If this function fails, the return value is NULL. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/wingdi/nf-wingdi-setcolorspace HCOLORSPACE SetColorSpace( HDC hdc, HCOLORSPACE - // hcs ); - [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] - [PInvokeData("wingdi.h", MSDNShortId = "037c864f-f8ec-4467-9236-74ea4493d743")] - public static extern HCOLORSPACE SetColorSpace(HDC hdc, HCOLORSPACE hcs); - - /// - /// The SetDeviceGammaRamp function sets the gamma ramp on direct color display boards having drivers that support - /// downloadable gamma ramps in hardware. - /// - /// Specifies the device context of the direct color display board in question. - /// - /// Pointer to a buffer containing the gamma ramp to be set. The gamma ramp is specified in three arrays of 256 WORD elements - /// each, which contain the mapping between RGB values in the frame buffer and digital-analog-converter (DAC ) values. The sequence - /// of the arrays is red, green, blue. The RGB values must be stored in the most significant bits of each WORD to increase DAC independence. - /// - /// - /// If this function succeeds, the return value is TRUE. - /// If this function fails, the return value is FALSE. - /// - /// - /// Direct color display modes do not use color lookup tables and are usually 16, 24, or 32 bit. Not all direct color video boards - /// support loadable gamma ramps. SetDeviceGammaRamp succeeds only for devices with drivers that support downloadable gamma - /// ramps in hardware. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/wingdi/nf-wingdi-setdevicegammaramp - // BOOL SetDeviceGammaRamp( HDC hdc, LPVOID lpRamp ); - [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] - [PInvokeData("wingdi.h", MSDNShortId = "8e4cc9a4-f292-47a1-a12a-43a479326ca7")] - [return: MarshalAs(UnmanagedType.Bool)] - public static extern bool SetDeviceGammaRamp(HDC hdc, IntPtr lpRamp); - - /// - /// The SetICMMode function causes Image Color Management to be enabled, disabled, or queried on a given device context (DC). - /// - /// Identifies handle to the device context. - /// - /// Turns on and off image color management. This parameter can take one of the following constant values. - /// - /// - /// Value - /// Meaning - /// - /// - /// ICM_ON - /// Turns on color management. Turns off old-style color correction of halftones. - /// - /// - /// ICM_OFF - /// Turns off color management. Turns on old-style color correction of halftones. - /// - /// - /// ICM_QUERY - /// Queries the current state of color management. - /// - /// - /// ICM_DONE_OUTSIDEDC + /// CA_LOG_FILTER /// - /// Turns off color management inside DC. Under Windows 2000, also turns off old-style color correction of halftones. Not supported - /// under Windows 95. + /// Specifies that a logarithmic function should be applied to the final density of the output colors. This will increase the + /// color contrast when the luminance is low. /// /// /// - /// - /// - /// If this function succeeds, the return value is a nonzero value. - /// If this function fails, the return value is zero. - /// - /// If ICM_QUERY is specified and the function succeeds, the nonzero value returned is ICM_ON or ICM_OFF to indicate the current mode. - /// - /// - /// - /// If the system cannot find an ICC color profile to match the state of the device, SetICMMode fails and returns zero. - /// - /// Once WCS is enabled for a device context (DC), colors passed into the DC using most Win32 API functions are color matched. The - /// primary exceptions are BitBlt and StretchBlt. The assumption is that when performing a bit block transfer (blit) - /// from one DC to another, the two DCs are already compatible and need no color correction. If this is not the case, color - /// correction may be performed. Specifically, if a device independent bitmap (DIB) is used as the source for a blit, and the blit is - /// performed into a DC that has WCS enabled, color matching will be performed. If this is not what you want, turn WCS off for the - /// destination DC by calling SetICMMode before calling BitBlt or StretchBlt. - /// - /// - /// If the CreateCompatibleDC function is used to create a bitmap in a DC, it is possible for the bitmap to be color matched - /// twice, once when it is created and once when a blit is performed. The reason is that a bitmap in a DC created by the - /// CreateCompatibleDC function acquires the current brush, pens, and palette of the source DC. However, WCS will be disabled - /// by default for the new DC. If WCS is later enabled for the new DC by using the SetICMMode function, a color correction - /// will be done. To prevent double color corrections through the use of the CreateCompatibleDC function, use the - /// SetICMMode function to turn WCS off for the source DC before the CreateCompatibleDC function is called. - /// - /// - /// When a compatible DC is created from a printer's DC (see CreateCompatibleDC ), the default is for color matching to always - /// be performed if it is enabled for the printer's DC. The default color profile for the printer is used when a blit is performed - /// into the printer's DC using SetDIBitsToDevice or StretchDIBits. If this is not what you want, turn WCS off for the - /// printer's DC by calling SetICMMode before calling SetDIBitsToDevice or StretchDIBits. - /// - /// - /// Also, when printing to a printer's DC with WCS turned on, the SetICMMode function needs to be called after every call to - /// the StartPage function to turn back on WCS. The StartPage function calls the RestoreDC and SaveDC - /// functions, which result in WCS being turned off for the printer's DC. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/wingdi/nf-wingdi-seticmmode int SetICMMode( HDC hdc, int mode ); - [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] - [PInvokeData("wingdi.h", MSDNShortId = "40d70c1f-c580-43c4-b44b-6c9388e138fb")] - public static extern int SetICMMode(HDC hdc, ICM mode); + /// + public CA_FLAGS caFlags; /// - /// The SetICMProfile function sets a specified color profile as the output profile for a specified device context (DC). - /// - /// Specifies a device context in which to set the color profile. - /// Specifies the path name of the color profile to be set. - /// - /// If this function succeeds, the return value is TRUE. - /// If this function fails, the return value is FALSE. - /// - /// /// - /// SetICMProfile associates a color profile with a device context. It becomes the output profile for that device context. The - /// color profile does not have to be associated with any particular device. Device-independent profiles such as sRGB can also be - /// used. If the color profile is not associated with a hardware device, it will be returned by GetICMProfile, but not by EnumICMProfiles. + /// The type of standard light source under which the image is viewed. This member may be set to one of the following values. /// - /// - /// Note that under Windows 95 or later, the PostScript device driver for printers assumes a CMYK color model. Therefore, all - /// PostScript printers must use a CMYK color profile. Windows 2000 does not have this limitation. - /// - /// SetICMProfile supports only RGB profiles in compatible DCs. - /// - /// Windows 95/98/Me:SetICMProfileW is supported by the Microsoft Layer for Unicode. To use this, you must add certain - /// files to your application, as outlined in Microsoft Layer for Unicode on Windows 95/98/Me Systems. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/wingdi/nf-wingdi-seticmprofilew BOOL SetICMProfileW( HDC hdc, LPWSTR lpFileName ); - [DllImport(Lib.Gdi32, SetLastError = false, CharSet = CharSet.Auto)] - [PInvokeData("wingdi.h", MSDNShortId = "c95f6536-9377-4766-9eb6-004a41bcf6c5")] - [return: MarshalAs(UnmanagedType.Bool)] - public static extern bool SetICMProfile(HDC hdc, string lpFileName); - - /// - /// The SetPaletteEntries function sets RGB (red, green, blue) color values and flags in a range of entries in a logical palette. - /// - /// A handle to the logical palette. - /// The first logical-palette entry to be set. - /// The number of logical-palette entries to be set. - /// - /// A pointer to the first member of an array of PALETTEENTRY structures containing the RGB values and flags. - /// - /// - /// If the function succeeds, the return value is the number of entries that were set in the logical palette. - /// If the function fails, the return value is zero. - /// - /// - /// - /// An application can determine whether a device supports palette operations by calling the GetDeviceCaps function and specifying - /// the RASTERCAPS constant. - /// - /// - /// Even if a logical palette has been selected and realized, changes to the palette do not affect the physical palette in the - /// surface. RealizePalette must be called again to set the new logical palette into the surface. - /// - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/wingdi/nf-wingdi-setpaletteentries UINT SetPaletteEntries( HPALETTE hpal, - // UINT iStart, UINT cEntries, const PALETTEENTRY *pPalEntries ); - [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] - [PInvokeData("wingdi.h", MSDNShortId = "df38f482-75ba-4800-8b26-92204c63255e")] - public static extern uint SetPaletteEntries(HPALETTE hpal, uint iStart, uint cEntries, [In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 2)] PALETTEENTRY[] pPalEntries); - - /// - /// The SetSystemPaletteUse function allows an application to specify whether the system palette contains 2 or 20 static - /// colors. The default system palette contains 20 static colors. (Static colors cannot be changed when an application realizes a - /// logical palette.) - /// - /// A handle to the device context. This device context must refer to a device that supports color palettes. - /// - /// The new use of the system palette. This parameter can be one of the following values. /// /// /// Value /// Meaning /// /// - /// SYSPAL_NOSTATIC - /// The system palette contains two static colors (black and white). + /// ILLUMINANT_DEVICE_DEFAULT + /// Device's default. Standard used by output devices. /// /// - /// SYSPAL_NOSTATIC256 - /// The system palette contains no static colors. + /// ILLUMINANT_A + /// Tungsten lamp. /// /// - /// SYSPAL_STATIC - /// The system palette contains static colors that will not change when an application realizes its logical palette. + /// ILLUMINANT_B + /// Noon sunlight. + /// + /// + /// ILLUMINANT_C + /// NTSC daylight. + /// + /// + /// ILLUMINANT_D50 + /// Normal print. + /// + /// + /// ILLUMINANT_D55 + /// Bond paper print. + /// + /// + /// ILLUMINANT_D65 + /// Standard daylight. Standard for CRTs and pictures. + /// + /// + /// ILLUMINANT_D75 + /// Northern daylight. + /// + /// + /// ILLUMINANT_F2 + /// Cool white lamp. + /// + /// + /// ILLUMINANT_TUNGSTEN + /// Same as ILLUMINANT_A. + /// + /// + /// ILLUMINANT_DAYLIGHT + /// Same as ILLUMINANT_C. + /// + /// + /// ILLUMINANT_FLUORESCENT + /// Same as ILLUMINANT_F2. + /// + /// + /// ILLUMINANT_NTSC + /// Same as ILLUMINANT_C. /// /// - /// - /// - /// - /// If the function succeeds, the return value is the previous system palette. It can be either SYSPAL_NOSTATIC, SYSPAL_NOSTATIC256, - /// or SYSPAL_STATIC. - /// - /// If the function fails, the return value is SYSPAL_ERROR. - /// - /// - /// - /// An application can determine whether a device supports palette operations by calling the GetDeviceCaps function and specifying - /// the RASTERCAPS constant. - /// - /// - /// When an application window moves to the foreground and the SYSPAL_NOSTATIC value is set, the application must call the - /// GetSysColor function to save the current system colors setting. It must also call SetSysColors to set reasonable values using - /// only black and white. When the application returns to the background or terminates, the previous system colors must be restored. - /// - /// If the function returns SYSPAL_ERROR, the specified device context is invalid or does not support color palettes. - /// An application must call this function only when its window is maximized and has the input focus. - /// - /// If an application calls SetSystemPaletteUse with uUsage set to SYSPAL_NOSTATIC, the system continues to set aside two - /// entries in the system palette for pure white and pure black, respectively. - /// - /// After calling this function with uUsage set to SYSPAL_NOSTATIC, an application must take the following steps: - /// - /// - /// Realize the logical palette. - /// - /// - /// Call the GetSysColor function to save the current system-color settings. - /// + /// + public ILLUMINANT caIlluminantIndex; + + /// + /// Specifies the n power gamma-correction value for the red primary of the source colors. The value must be in the range from + /// 2500 to 65,000. A value of 10,000 means no gamma correction. + /// + public ushort caRedGamma; + + /// + /// Specifies the n power gamma-correction value for the green primary of the source colors. The value must be in the range from + /// 2500 to 65,000. A value of 10,000 means no gamma correction. + /// + public ushort caGreenGamma; + + /// + /// Specifies the n power gamma-correction value for the blue primary of the source colors. The value must be in the range from + /// 2500 to 65,000. A value of 10,000 means no gamma correction. + /// + public ushort caBlueGamma; + + /// + /// The black reference for the source colors. Any colors that are darker than this are treated as black. The value must be in + /// the range from 0 to 4000. + /// + public ushort caReferenceBlack; + + /// + /// The white reference for the source colors. Any colors that are lighter than this are treated as white. The value must be in + /// the range from 6000 to 10,000. + /// + public ushort caReferenceWhite; + + /// + /// The amount of contrast to be applied to the source object. The value must be in the range from -100 to 100. A value of 0 + /// means no contrast adjustment. + /// + public short caContrast; + + /// + /// The amount of brightness to be applied to the source object. The value must be in the range from -100 to 100. A value of 0 + /// means no brightness adjustment. + /// + public short caBrightness; + + /// + /// The amount of colorfulness to be applied to the source object. The value must be in the range from -100 to 100. A value of 0 + /// means no colorfulness adjustment. + /// + public short caColorfulness; + + /// + /// The amount of red or green tint adjustment to be applied to the source object. The value must be in the range from -100 to + /// 100. Positive numbers adjust toward red and negative numbers adjust toward green. Zero means no tint adjustment. + /// + public short caRedGreenTint; + } + + /// The LOGCOLORSPACE structure contains information that defines a logical color space. + /// + /// Like palettes, but unlike pens and brushes, a pointer must be passed when creating a LogColorSpace. + /// + /// If the lcsCSType member is set to LCS_sRGB or LCS_WINDOWS_COLOR_SPACE, the other members of this structure are ignored, + /// and WCS uses the sRGB color space. The lcsEndpoints,lcsGammaRed, lcsGammaGreen, and lcsGammaBlue members are + /// used to describe the logical color space. The lcsEndpoints member is a CIEXYZTRIPLE that contains the x, y, and z + /// values of the color space's RGB endpoint. + /// + /// + /// The required DWORD bit format for the lcsGammaRed, lcsGammaGreen, and lcsGammaBlue is an 8.8 fixed point + /// interger left-shifted by 8 bits. This means 8 interger bits are followed by 8 fraction bits. Taking the bit shift into account, + /// the required format of the 32-bit DWORD is: + /// + /// 00000000nnnnnnnnffffffff00000000 + /// + /// Whenever the lcsFilename member contains a file name and the lcsCSType member is set to LCS_CALIBRATED_RGB, WCS + /// ignores the other members of this structure. It uses the color space in the file as the color space to which this + /// LOGCOLORSPACE structure refers. + /// + /// The relation between tri-stimulus values X,Y,Z and chromaticity values x,y,z is as follows: + /// x = X/(X+Y+Z) + /// y = Y/(X+Y+Z) + /// z = Z/(X+Y+Z) + /// + /// If the lcsCSType member is set to LCS_sRGB or LCS_WINDOWS_COLOR_SPACE, the other members of this structure are ignored, and ICM + /// uses the sRGB color space. Appliations should still initialize the rest of the structure since CreateProfileFromLogColorSpace + /// ignores lcsCSType member and uses lcsEndpoints, lcsGammaRed, lcsGammaGreen, lcsGammaBlue members to create a profile, which may + /// not be initialized in case of LCS_sRGB or LCS_WINDOWS_COLOR_SPACE color spaces. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/wingdi/ns-wingdi-logcolorspacea typedef struct tagLOGCOLORSPACEA { DWORD + // lcsSignature; DWORD lcsVersion; DWORD lcsSize; LCSCSTYPE lcsCSType; LCSGAMUTMATCH lcsIntent; CIEXYZTRIPLE lcsEndpoints; DWORD + // lcsGammaRed; DWORD lcsGammaGreen; DWORD lcsGammaBlue; CHAR lcsFilename[MAX_PATH]; } LOGCOLORSPACEA, *LPLOGCOLORSPACEA; + [PInvokeData("wingdi.h", MSDNShortId = "b08aec07-6ac0-47be-8dc9-d604d94dedde")] + [StructLayout(LayoutKind.Sequential)] + public struct LOGCOLORSPACE + { + private const uint LCS_SIGNATURE = 0x50534f43; + + /// Color space signature. At present, this member should always be set to LCS_SIGNATURE. + public uint lcsSignature; + + /// Version number; must be 0x400. + public uint lcsVersion; + + /// Size of this structure, in bytes. + public uint lcsSize; + + /// + /// Color space type. The member can be one of the following values. + /// + /// + /// Value + /// Meaning + /// /// + /// LCS_CALIBRATED_RGB /// - /// Call the SetSysColors function to set the system colors to reasonable values using black and white. For example, adjacent or - /// overlapping items (such as window frames and borders) should be set to black and white, respectively. + /// Color values are calibrated RGB values. The values are translated using the endpoints specified by the lcsEndpoints member + /// before being passed to the device. /// /// /// - /// Send the WM_SYSCOLORCHANGE message to other top-level windows to allow them to be redrawn with the new system colors. + /// LCS_sRGB + /// Color values are values are sRGB values. + /// + /// + /// LCS_WINDOWS_COLOR_SPACE + /// Color values are Windows default color space color values. /// /// - /// When the application's window loses focus or closes, the application must perform the following steps: - /// + /// If LCS_CALIBRATED_RGB is not specified, the lcsEndpoints member is ignored. + /// + public LCSCSTYPE lcsCSType; + + /// + /// The gamut mapping method. This member can be one of the following values. + /// + /// + /// Value + /// Intent + /// ICC Name + /// Meaning + /// /// - /// Call SetSystemPaletteUse with the uUsage parameter set to SYSPAL_STATIC. + /// LCS_GM_ABS_COLORIMETRIC + /// Match + /// Absolute Colorimetric + /// Maintain the white point. Match the colors to their nearest color in the destination gamut. /// /// - /// Realize the logical palette. + /// LCS_GM_BUSINESS + /// Graphic + /// Saturation + /// Maintain saturation. Used for business charts and other situations in which undithered colors are required. /// /// - /// Restore the system colors to their previous values. + /// LCS_GM_GRAPHICS + /// Proof + /// Relative Colorimetric + /// Maintain colorimetric match. Used for graphic designs and named colors. /// /// - /// Send the WM_SYSCOLORCHANGE message. + /// LCS_GM_IMAGES + /// Picture + /// Perceptual + /// Maintain contrast. Used for photographs and natural images. /// /// - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/wingdi/nf-wingdi-setsystempaletteuse UINT SetSystemPaletteUse( HDC hdc, UINT - // use ); - [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] - [PInvokeData("wingdi.h", MSDNShortId = "6ff245d3-1bcc-4778-a595-c1eb16531ad3")] - public static extern SYSPAL SetSystemPaletteUse(HDC hdc, SYSPAL use); + /// + public LCSGAMUTMATCH lcsIntent; + + /// Red, green, blue endpoints. + public CIEXYZTRIPLE lcsEndpoints; + + /// Scale of the red coordinate. + public uint lcsGammaRed; + + /// Scale of the green coordinate. + public uint lcsGammaGreen; + + /// Scale of the blue coordinate. + public uint lcsGammaBlue; /// - /// The UnrealizeObject function resets the origin of a brush or resets a logical palette. If the hgdiobj parameter is a - /// handle to a brush, UnrealizeObject directs the system to reset the origin of the brush the next time it is selected. If - /// the hgdiobj parameter is a handle to a logical palette, UnrealizeObject directs the system to realize the palette as - /// though it had not previously been realized. The next time the application calls the RealizePalette function for the specified - /// palette, the system completely remaps the logical palette to the system palette. + /// A null-terminated string that names a color profile file. This member is typically set to zero, but may be used to set the + /// color space to be exactly as specified by the color profile. This is useful for devices that input color values for a + /// specific printer, or when using an installable image color matcher. If a color profile is specified, all other members of + /// this structure should be set to reasonable values, even if the values are not completely accurate. /// - /// A handle to the logical palette to be reset. - /// - /// If the function succeeds, the return value is nonzero. - /// If the function fails, the return value is zero. - /// - /// - /// - /// The UnrealizeObject function should not be used with stock objects. For example, the default palette, obtained by calling - /// GetStockObject (DEFAULT_PALETTE), is a stock object. - /// - /// A palette identified by hgdiobj can be the currently selected palette of a device context. - /// - /// If hgdiobj is a brush, UnrealizeObject does nothing, and the function returns TRUE. Use SetBrushOrgEx to set the - /// origin of a brush. - /// - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/wingdi/nf-wingdi-unrealizeobject BOOL UnrealizeObject( HGDIOBJ h ); - [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] - [PInvokeData("wingdi.h", MSDNShortId = "b84cd0b3-fdf1-4f12-bc45-308032d6d698")] - [return: MarshalAs(UnmanagedType.Bool)] - public static extern bool UnrealizeObject(HGDIOBJ h); + [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 260)] + public string lcsFilename; - /// - /// The UpdateColors function updates the client area of the specified device context by remapping the current colors in the - /// client area to the currently realized logical palette. - /// - /// A handle to the device context. - /// - /// If the function succeeds, the return value is nonzero. - /// If the function fails, the return value is zero. - /// - /// - /// - /// An application can determine whether a device supports palette operations by calling the GetDeviceCaps function and specifying - /// the RASTERCAPS constant. - /// - /// - /// An inactive window with a realized logical palette may call UpdateColors as an alternative to redrawing its client area - /// when the system palette changes. - /// - /// - /// The UpdateColors function typically updates a client area faster than redrawing the area. However, because - /// UpdateColors performs the color translation based on the color of each pixel before the system palette changed, each call - /// to this function results in the loss of some color accuracy. - /// - /// This function must be called soon after a WM_PALETTECHANGED message is received. - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/wingdi/nf-wingdi-updatecolors BOOL UpdateColors( HDC hdc ); - [DllImport(Lib.Gdi32, SetLastError = false, ExactSpelling = true)] - [PInvokeData("wingdi.h", MSDNShortId = "61dfd579-3fc9-4e0a-bfd9-d04c6f918fd8")] - [return: MarshalAs(UnmanagedType.Bool)] - public static extern bool UpdateColors(HDC hdc); + /// The default structure with size and default fields preset. + public static readonly LOGCOLORSPACE Default = new LOGCOLORSPACE { lcsSignature = LCS_SIGNATURE, lcsVersion = 0x400, lcsSize = (uint)Marshal.SizeOf(typeof(LOGCOLORSPACE)) }; + } - /// The CIEXYZ structure contains the x,y, and z coordinates of a specific color in a specified color space. - // https://docs.microsoft.com/en-us/windows/win32/api/wingdi/ns-wingdi-ciexyz typedef struct tagCIEXYZ { FXPT2DOT30 ciexyzX; - // FXPT2DOT30 ciexyzY; FXPT2DOT30 ciexyzZ; } CIEXYZ; - [PInvokeData("wingdi.h", MSDNShortId = "3735c143-8eb3-4b91-a81e-5bc6bda1dfaa")] - [StructLayout(LayoutKind.Sequential)] - public struct CIEXYZ - { - /// The x coordinate in fix point (2.30). - public int ciexyzX; + /// + /// The RGBTRIPLE structure describes a color consisting of relative intensities of red, green, and blue. The + /// bmciColors member of the BITMAPCOREINFO structure consists of an array of RGBTRIPLE structures. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/wingdi/ns-wingdi-rgbtriple typedef struct tagRGBTRIPLE { BYTE rgbtBlue; BYTE + // rgbtGreen; BYTE rgbtRed; } RGBTRIPLE, *PRGBTRIPLE, *NPRGBTRIPLE, *LPRGBTRIPLE; + [PInvokeData("wingdi.h", MSDNShortId = "bc1467a5-0027-4f22-bfc9-1deab562c573")] + [StructLayout(LayoutKind.Sequential)] + public struct RGBTRIPLE + { + /// The intensity of blue in the color. + public byte rgbtBlue; - /// The y coordinate in fix point (2.30). - public int ciexyzY; + /// The intensity of green in the color. + public byte rgbtGreen; - /// The z coordinate in fix point (2.30). - public int ciexyzZ; - } + /// The intensity of red in the color. + public byte rgbtRed; + } - /// - /// The CIEXYZTRIPLE structure contains the x,y, and z coordinates of the three colors that correspond to the red, green, and - /// blue endpoints for a specified logical color space. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/wingdi/ns-wingdi-ciexyztriple typedef struct tagICEXYZTRIPLE { CIEXYZ - // ciexyzRed; CIEXYZ ciexyzGreen; CIEXYZ ciexyzBlue; } CIEXYZTRIPLE; - [PInvokeData("wingdi.h", MSDNShortId = "cf4473b0-7e54-42d1-a013-2442a540daee")] - [StructLayout(LayoutKind.Sequential)] - public struct CIEXYZTRIPLE - { - /// The xyz coordinates of red endpoint. - public CIEXYZ ciexyzRed; + /// Provides a for that is disposed using . + public class SafeHCOLORSPACE : SafeHANDLE + { + /// Initializes a new instance of the class and assigns an existing handle. + /// An object that represents the pre-existing handle to use. + /// + /// to reliably release the handle during the finalization phase; otherwise, (not recommended). + /// + public SafeHCOLORSPACE(IntPtr preexistingHandle, bool ownsHandle = true) : base(preexistingHandle, ownsHandle) { } - /// The xyz coordinates of green endpoint. - public CIEXYZ ciexyzGreen; + /// Initializes a new instance of the class. + private SafeHCOLORSPACE() : base() { } - /// The xyz coordinates of blue endpoint. - public CIEXYZ ciexyzBlue; - } + /// Performs an implicit conversion from to . + /// The safe handle instance. + /// The result of the conversion. + public static implicit operator HCOLORSPACE(SafeHCOLORSPACE h) => h.handle; - /// - /// The COLORADJUSTMENT structure defines the color adjustment values used by the StretchBlt and StretchDIBits functions when - /// the stretch mode is HALFTONE. You can set the color adjustment values by calling the SetColorAdjustment function. - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/wingdi/ns-wingdi-coloradjustment typedef struct tagCOLORADJUSTMENT { WORD - // caSize; WORD caFlags; WORD caIlluminantIndex; WORD caRedGamma; WORD caGreenGamma; WORD caBlueGamma; WORD caReferenceBlack; WORD - // caReferenceWhite; SHORT caContrast; SHORT caBrightness; SHORT caColorfulness; SHORT caRedGreenTint; } COLORADJUSTMENT, - // *PCOLORADJUSTMENT, *LPCOLORADJUSTMENT; - [PInvokeData("wingdi.h", MSDNShortId = "9a080f60-0bce-46b6-b8a8-f534ff83a0a8")] - [StructLayout(LayoutKind.Sequential)] - public struct COLORADJUSTMENT - { - /// The size, in bytes, of the structure. - public ushort caSize; - - /// - /// - /// Specifies how the output image should be prepared. This member may be set to NULL or any combination of the following values. - /// - /// - /// - /// Value - /// Meaning - /// - /// - /// CA_NEGATIVE - /// Specifies that the negative of the original image should be displayed. - /// - /// - /// CA_LOG_FILTER - /// - /// Specifies that a logarithmic function should be applied to the final density of the output colors. This will increase the - /// color contrast when the luminance is low. - /// - /// - /// - /// - public CA_FLAGS caFlags; - - /// - /// - /// The type of standard light source under which the image is viewed. This member may be set to one of the following values. - /// - /// - /// - /// Value - /// Meaning - /// - /// - /// ILLUMINANT_DEVICE_DEFAULT - /// Device's default. Standard used by output devices. - /// - /// - /// ILLUMINANT_A - /// Tungsten lamp. - /// - /// - /// ILLUMINANT_B - /// Noon sunlight. - /// - /// - /// ILLUMINANT_C - /// NTSC daylight. - /// - /// - /// ILLUMINANT_D50 - /// Normal print. - /// - /// - /// ILLUMINANT_D55 - /// Bond paper print. - /// - /// - /// ILLUMINANT_D65 - /// Standard daylight. Standard for CRTs and pictures. - /// - /// - /// ILLUMINANT_D75 - /// Northern daylight. - /// - /// - /// ILLUMINANT_F2 - /// Cool white lamp. - /// - /// - /// ILLUMINANT_TUNGSTEN - /// Same as ILLUMINANT_A. - /// - /// - /// ILLUMINANT_DAYLIGHT - /// Same as ILLUMINANT_C. - /// - /// - /// ILLUMINANT_FLUORESCENT - /// Same as ILLUMINANT_F2. - /// - /// - /// ILLUMINANT_NTSC - /// Same as ILLUMINANT_C. - /// - /// - /// - public ILLUMINANT caIlluminantIndex; - - /// - /// Specifies the n power gamma-correction value for the red primary of the source colors. The value must be in the range from - /// 2500 to 65,000. A value of 10,000 means no gamma correction. - /// - public ushort caRedGamma; - - /// - /// Specifies the n power gamma-correction value for the green primary of the source colors. The value must be in the range from - /// 2500 to 65,000. A value of 10,000 means no gamma correction. - /// - public ushort caGreenGamma; - - /// - /// Specifies the n power gamma-correction value for the blue primary of the source colors. The value must be in the range from - /// 2500 to 65,000. A value of 10,000 means no gamma correction. - /// - public ushort caBlueGamma; - - /// - /// The black reference for the source colors. Any colors that are darker than this are treated as black. The value must be in - /// the range from 0 to 4000. - /// - public ushort caReferenceBlack; - - /// - /// The white reference for the source colors. Any colors that are lighter than this are treated as white. The value must be in - /// the range from 6000 to 10,000. - /// - public ushort caReferenceWhite; - - /// - /// The amount of contrast to be applied to the source object. The value must be in the range from -100 to 100. A value of 0 - /// means no contrast adjustment. - /// - public short caContrast; - - /// - /// The amount of brightness to be applied to the source object. The value must be in the range from -100 to 100. A value of 0 - /// means no brightness adjustment. - /// - public short caBrightness; - - /// - /// The amount of colorfulness to be applied to the source object. The value must be in the range from -100 to 100. A value of 0 - /// means no colorfulness adjustment. - /// - public short caColorfulness; - - /// - /// The amount of red or green tint adjustment to be applied to the source object. The value must be in the range from -100 to - /// 100. Positive numbers adjust toward red and negative numbers adjust toward green. Zero means no tint adjustment. - /// - public short caRedGreenTint; - } - - /// The LOGCOLORSPACE structure contains information that defines a logical color space. - /// - /// Like palettes, but unlike pens and brushes, a pointer must be passed when creating a LogColorSpace. - /// - /// If the lcsCSType member is set to LCS_sRGB or LCS_WINDOWS_COLOR_SPACE, the other members of this structure are ignored, - /// and WCS uses the sRGB color space. The lcsEndpoints,lcsGammaRed, lcsGammaGreen, and lcsGammaBlue members are - /// used to describe the logical color space. The lcsEndpoints member is a CIEXYZTRIPLE that contains the x, y, and z - /// values of the color space's RGB endpoint. - /// - /// - /// The required DWORD bit format for the lcsGammaRed, lcsGammaGreen, and lcsGammaBlue is an 8.8 fixed point - /// interger left-shifted by 8 bits. This means 8 interger bits are followed by 8 fraction bits. Taking the bit shift into account, - /// the required format of the 32-bit DWORD is: - /// - /// 00000000nnnnnnnnffffffff00000000 - /// - /// Whenever the lcsFilename member contains a file name and the lcsCSType member is set to LCS_CALIBRATED_RGB, WCS - /// ignores the other members of this structure. It uses the color space in the file as the color space to which this - /// LOGCOLORSPACE structure refers. - /// - /// The relation between tri-stimulus values X,Y,Z and chromaticity values x,y,z is as follows: - /// x = X/(X+Y+Z) - /// y = Y/(X+Y+Z) - /// z = Z/(X+Y+Z) - /// - /// If the lcsCSType member is set to LCS_sRGB or LCS_WINDOWS_COLOR_SPACE, the other members of this structure are ignored, and ICM - /// uses the sRGB color space. Appliations should still initialize the rest of the structure since CreateProfileFromLogColorSpace - /// ignores lcsCSType member and uses lcsEndpoints, lcsGammaRed, lcsGammaGreen, lcsGammaBlue members to create a profile, which may - /// not be initialized in case of LCS_sRGB or LCS_WINDOWS_COLOR_SPACE color spaces. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/wingdi/ns-wingdi-logcolorspacea typedef struct tagLOGCOLORSPACEA { DWORD - // lcsSignature; DWORD lcsVersion; DWORD lcsSize; LCSCSTYPE lcsCSType; LCSGAMUTMATCH lcsIntent; CIEXYZTRIPLE lcsEndpoints; DWORD - // lcsGammaRed; DWORD lcsGammaGreen; DWORD lcsGammaBlue; CHAR lcsFilename[MAX_PATH]; } LOGCOLORSPACEA, *LPLOGCOLORSPACEA; - [PInvokeData("wingdi.h", MSDNShortId = "b08aec07-6ac0-47be-8dc9-d604d94dedde")] - [StructLayout(LayoutKind.Sequential)] - public struct LOGCOLORSPACE - { - private const uint LCS_SIGNATURE = 0x50534f43; - - /// Color space signature. At present, this member should always be set to LCS_SIGNATURE. - public uint lcsSignature; - - /// Version number; must be 0x400. - public uint lcsVersion; - - /// Size of this structure, in bytes. - public uint lcsSize; - - /// - /// Color space type. The member can be one of the following values. - /// - /// - /// Value - /// Meaning - /// - /// - /// LCS_CALIBRATED_RGB - /// - /// Color values are calibrated RGB values. The values are translated using the endpoints specified by the lcsEndpoints member - /// before being passed to the device. - /// - /// - /// - /// LCS_sRGB - /// Color values are values are sRGB values. - /// - /// - /// LCS_WINDOWS_COLOR_SPACE - /// Color values are Windows default color space color values. - /// - /// - /// If LCS_CALIBRATED_RGB is not specified, the lcsEndpoints member is ignored. - /// - public LCSCSTYPE lcsCSType; - - /// - /// The gamut mapping method. This member can be one of the following values. - /// - /// - /// Value - /// Intent - /// ICC Name - /// Meaning - /// - /// - /// LCS_GM_ABS_COLORIMETRIC - /// Match - /// Absolute Colorimetric - /// Maintain the white point. Match the colors to their nearest color in the destination gamut. - /// - /// - /// LCS_GM_BUSINESS - /// Graphic - /// Saturation - /// Maintain saturation. Used for business charts and other situations in which undithered colors are required. - /// - /// - /// LCS_GM_GRAPHICS - /// Proof - /// Relative Colorimetric - /// Maintain colorimetric match. Used for graphic designs and named colors. - /// - /// - /// LCS_GM_IMAGES - /// Picture - /// Perceptual - /// Maintain contrast. Used for photographs and natural images. - /// - /// - /// - public LCSGAMUTMATCH lcsIntent; - - /// Red, green, blue endpoints. - public CIEXYZTRIPLE lcsEndpoints; - - /// Scale of the red coordinate. - public uint lcsGammaRed; - - /// Scale of the green coordinate. - public uint lcsGammaGreen; - - /// Scale of the blue coordinate. - public uint lcsGammaBlue; - - /// - /// A null-terminated string that names a color profile file. This member is typically set to zero, but may be used to set the - /// color space to be exactly as specified by the color profile. This is useful for devices that input color values for a - /// specific printer, or when using an installable image color matcher. If a color profile is specified, all other members of - /// this structure should be set to reasonable values, even if the values are not completely accurate. - /// - [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 260)] - public string lcsFilename; - - /// The default structure with size and default fields preset. - public static readonly LOGCOLORSPACE Default = new LOGCOLORSPACE { lcsSignature = LCS_SIGNATURE, lcsVersion = 0x400, lcsSize = (uint)Marshal.SizeOf(typeof(LOGCOLORSPACE)) }; - } - - /// - /// The RGBTRIPLE structure describes a color consisting of relative intensities of red, green, and blue. The - /// bmciColors member of the BITMAPCOREINFO structure consists of an array of RGBTRIPLE structures. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/wingdi/ns-wingdi-rgbtriple typedef struct tagRGBTRIPLE { BYTE rgbtBlue; BYTE - // rgbtGreen; BYTE rgbtRed; } RGBTRIPLE, *PRGBTRIPLE, *NPRGBTRIPLE, *LPRGBTRIPLE; - [PInvokeData("wingdi.h", MSDNShortId = "bc1467a5-0027-4f22-bfc9-1deab562c573")] - [StructLayout(LayoutKind.Sequential)] - public struct RGBTRIPLE - { - /// The intensity of blue in the color. - public byte rgbtBlue; - - /// The intensity of green in the color. - public byte rgbtGreen; - - /// The intensity of red in the color. - public byte rgbtRed; - } - - /// Provides a for that is disposed using . - public class SafeHCOLORSPACE : SafeHANDLE - { - /// Initializes a new instance of the class and assigns an existing handle. - /// An object that represents the pre-existing handle to use. - /// - /// to reliably release the handle during the finalization phase; otherwise, (not recommended). - /// - public SafeHCOLORSPACE(IntPtr preexistingHandle, bool ownsHandle = true) : base(preexistingHandle, ownsHandle) { } - - /// Initializes a new instance of the class. - private SafeHCOLORSPACE() : base() { } - - /// Performs an implicit conversion from to . - /// The safe handle instance. - /// The result of the conversion. - public static implicit operator HCOLORSPACE(SafeHCOLORSPACE h) => h.handle; - - /// - protected override bool InternalReleaseHandle() => DeleteColorSpace(handle); - } + /// + protected override bool InternalReleaseHandle() => DeleteColorSpace(handle); } } \ No newline at end of file diff --git a/PInvoke/Kernel32/AppModel.cs b/PInvoke/Kernel32/AppModel.cs index a4c948ca..69b178a7 100644 --- a/PInvoke/Kernel32/AppModel.cs +++ b/PInvoke/Kernel32/AppModel.cs @@ -1,2554 +1,2621 @@ -using System; +#nullable enable +using System; +using System.Linq; using System.Runtime.InteropServices; using System.Text; +using Vanara.Extensions; -namespace Vanara.PInvoke +namespace Vanara.PInvoke; + +public static partial class Kernel32 { - public static partial class Kernel32 + /// + /// Defines options that can be applied when adding a run-time reference to a framework package by using the AddPackageDependency function. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/appmodel/ne-appmodel-addpackagedependencyoptions typedef enum + // AddPackageDependencyOptions { AddPackageDependencyOptions_None, AddPackageDependencyOptions_PrependIfRankCollision } ; + [PInvokeData("appmodel.h", MSDNShortId = "NE:appmodel.AddPackageDependencyOptions")] + public enum AddPackageDependencyOptions + { + /// No options are applied. + AddPackageDependencyOptions_None, + + /// + /// If multiple packages are present in the package graph with the same rank as the call to AddPackageDependency, the + /// resolved package is added before others of the same rank. + /// + AddPackageDependencyOptions_PrependIfRankCollision, + } + + /// + /// The AppPolicyCreateFileAccess enumeration indicates whether a process has full or restricted access to the IO devices (file, + /// file stream, directory, physical disk, volume, console buffer, tape drive, communications resource, mailslot, and pipe). + /// + // typedef enum AppPolicyCreateFileAccess { AppPolicyCreateFileAccess_Full = 0, AppPolicyCreateFileAccess_Limited = 1} + // AppPolicyCreateFileAccess; https://msdn.microsoft.com/en-us/library/windows/desktop/mt829654(v=vs.85).aspx + [PInvokeData("AppModel.h", MSDNShortId = "mt829654")] + public enum AppPolicyCreateFileAccess { /// - /// Defines options that can be applied when adding a run-time reference to a framework package by using the AddPackageDependency function. + /// Indicates that the process has full access to the IO devices. This value is expected for a desktop application, or for a + /// Desktop Bridge application. /// - // https://docs.microsoft.com/en-us/windows/win32/api/appmodel/ne-appmodel-addpackagedependencyoptions typedef enum - // AddPackageDependencyOptions { AddPackageDependencyOptions_None, AddPackageDependencyOptions_PrependIfRankCollision } ; - [PInvokeData("appmodel.h", MSDNShortId = "NE:appmodel.AddPackageDependencyOptions")] - public enum AddPackageDependencyOptions - { - /// No options are applied. - AddPackageDependencyOptions_None, + AppPolicyCreateFileAccess_Full, - /// - /// If multiple packages are present in the package graph with the same rank as the call to AddPackageDependency, the - /// resolved package is added before others of the same rank. - /// - AddPackageDependencyOptions_PrependIfRankCollision, - } + /// Indicates that the process has limited access to the IO devices. This value is expected for a UWP app. + AppPolicyCreateFileAccess_Limited, + } + + /// The AppPolicyProcessTerminationMethod enumeration indicates the method used to end a process. + // typedef enum AppPolicyProcessTerminationMethod { AppPolicyProcessTerminationMethod_ExitProcess = 0, + // AppPolicyProcessTerminationMethod_TerminateProcess = 1} AppPolicyProcessTerminationMethod; https://msdn.microsoft.com/en-us/library/windows/desktop/mt829659(v=vs.85).aspx + [PInvokeData("AppModel.h", MSDNShortId = "mt829659")] + public enum AppPolicyProcessTerminationMethod + { + /// + /// Allows DLLs to execute code at shutdown. This value is expected for a desktop application, or for a Desktop Bridge application. + /// + AppPolicyProcessTerminationMethod_ExitProcess, + + /// Immediately ends the process. This value is expected for a UWP app. + AppPolicyProcessTerminationMethod_TerminateProcess, + } + + /// + /// The AppPolicyShowDeveloperDiagnostic enumeration indicates the method used for a process to surface developer information, such + /// as asserts, to the user. + /// + // typedef enum AppPolicyShowDeveloperDiagnostic { AppPolicyShowDeveloperDiagnostic_None = 0, AppPolicyShowDeveloperDiagnostic_ShowUI + // = 1} AppPolicyShowDeveloperDiagnostic; https://msdn.microsoft.com/en-us/library/windows/desktop/mt829660(v=vs.85).aspx + [PInvokeData("AppModel.h", MSDNShortId = "mt829660")] + public enum AppPolicyShowDeveloperDiagnostic + { + /// Indicates that the process does not show developer diagnostics. This value is expected for a UWP app. + AppPolicyShowDeveloperDiagnostic_None, /// - /// The AppPolicyCreateFileAccess enumeration indicates whether a process has full or restricted access to the IO devices (file, - /// file stream, directory, physical disk, volume, console buffer, tape drive, communications resource, mailslot, and pipe). + /// Indicates that the process shows developer diagnostics UI. This value is expected for a desktop application, or for a + /// Desktop Bridge application. /// - // typedef enum AppPolicyCreateFileAccess { AppPolicyCreateFileAccess_Full = 0, AppPolicyCreateFileAccess_Limited = 1} - // AppPolicyCreateFileAccess; https://msdn.microsoft.com/en-us/library/windows/desktop/mt829654(v=vs.85).aspx - [PInvokeData("AppModel.h", MSDNShortId = "mt829654")] - public enum AppPolicyCreateFileAccess - { - /// - /// Indicates that the process has full access to the IO devices. This value is expected for a desktop application, or for a - /// Desktop Bridge application. - /// - AppPolicyCreateFileAccess_Full, + AppPolicyShowDeveloperDiagnostic_ShowUI, + } - /// Indicates that the process has limited access to the IO devices. This value is expected for a UWP app. - AppPolicyCreateFileAccess_Limited, - } + /// + /// The AppPolicyThreadInitializationType enumeration indicates the kind of initialization that should be automatically performed + /// for a process when beginthread[ex] creates a thread. + /// + // typedef enum AppPolicyThreadInitializationType { AppPolicyThreadInitializationType_None = 0, + // AppPolicyThreadInitializationType_InitializeWinRT = 1} AppPolicyThreadInitializationType; https://msdn.microsoft.com/en-us/library/windows/desktop/mt829661(v=vs.85).aspx + [PInvokeData("AppModel.h", MSDNShortId = "mt829661")] + public enum AppPolicyThreadInitializationType + { + /// Indicates that no initialization should be performed. + AppPolicyThreadInitializationType_None, - /// The AppPolicyProcessTerminationMethod enumeration indicates the method used to end a process. - // typedef enum AppPolicyProcessTerminationMethod { AppPolicyProcessTerminationMethod_ExitProcess = 0, - // AppPolicyProcessTerminationMethod_TerminateProcess = 1} AppPolicyProcessTerminationMethod; https://msdn.microsoft.com/en-us/library/windows/desktop/mt829659(v=vs.85).aspx - [PInvokeData("AppModel.h", MSDNShortId = "mt829659")] - public enum AppPolicyProcessTerminationMethod - { - /// - /// Allows DLLs to execute code at shutdown. This value is expected for a desktop application, or for a Desktop Bridge application. - /// - AppPolicyProcessTerminationMethod_ExitProcess, + /// Indicates that Windows Runtime initialization should be performed. + AppPolicyThreadInitializationType_InitializeWinRT, + } - /// Immediately ends the process. This value is expected for a UWP app. - AppPolicyProcessTerminationMethod_TerminateProcess, - } + /// + /// Specifies the processor architectures supported by a package. + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/appxpackaging/ne-appxpackaging-appx_package_architecture typedef enum + // APPX_PACKAGE_ARCHITECTURE { APPX_PACKAGE_ARCHITECTURE_X86 , APPX_PACKAGE_ARCHITECTURE_ARM , APPX_PACKAGE_ARCHITECTURE_X64 , + // APPX_PACKAGE_ARCHITECTURE_NEUTRAL , APPX_PACKAGE_ARCHITECTURE_ARM64 } ; + [PInvokeData("appxpackaging.h", MSDNShortId = "8BC7ABF0-448F-4405-AA82-49C6DB3F230C")] + public enum APPX_PACKAGE_ARCHITECTURE + { + /// The x86 processor architecture. + APPX_PACKAGE_ARCHITECTURE_X86 = 0, + + /// The ARM processor architecture. + APPX_PACKAGE_ARCHITECTURE_ARM = 5, + + /// The x64 processor architecture. + APPX_PACKAGE_ARCHITECTURE_X64 = 9, + + /// Any processor architecture. + APPX_PACKAGE_ARCHITECTURE_NEUTRAL = 11, + + /// The 64-bit ARM processor architecture. + APPX_PACKAGE_ARCHITECTURE_ARM64 = 12, + } + + /// Defines options that can be applied when creating a package dependency by using the TryCreatePackageDependency function. + // https://docs.microsoft.com/en-us/windows/win32/api/appmodel/ne-appmodel-createpackagedependencyoptions typedef enum + // CreatePackageDependencyOptions { CreatePackageDependencyOptions_None, + // CreatePackageDependencyOptions_DoNotVerifyDependencyResolution, CreatePackageDependencyOptions_ScopeIsSystem } ; + [PInvokeData("appmodel.h", MSDNShortId = "NE:appmodel.CreatePackageDependencyOptions")] + [Flags] + public enum CreatePackageDependencyOptions + { + /// No options are applied. + CreatePackageDependencyOptions_None = 0, /// - /// The AppPolicyShowDeveloperDiagnostic enumeration indicates the method used for a process to surface developer information, such - /// as asserts, to the user. + /// Disables dependency resolution when pinning a package dependency. This is useful for installers running as user contexts + /// other than the target user (for example, installers running as LocalSystem). /// - // typedef enum AppPolicyShowDeveloperDiagnostic { AppPolicyShowDeveloperDiagnostic_None = 0, AppPolicyShowDeveloperDiagnostic_ShowUI - // = 1} AppPolicyShowDeveloperDiagnostic; https://msdn.microsoft.com/en-us/library/windows/desktop/mt829660(v=vs.85).aspx - [PInvokeData("AppModel.h", MSDNShortId = "mt829660")] - public enum AppPolicyShowDeveloperDiagnostic + CreatePackageDependencyOptions_DoNotVerifyDependencyResolution = 1, + + /// + /// Defines the package dependency for the system, accessible to all users (by default, the package dependency is defined for a + /// specific user). This option requires the caller has administrative privileges. + /// + CreatePackageDependencyOptions_ScopeIsSystem = 2, + } + + /// Specifies how packages are to be processed. + // https://docs.microsoft.com/en-us/windows/desktop/appxpkg/package-constants + [PInvokeData("", MSDNShortId = "72E565C3-6CFD-47E3-8BAC-17D6E86B99DA")] + [Flags] + public enum PACKAGE_FLAGS : uint + { + /// The maximum number of apps in a package. + PACKAGE_APPLICATIONS_MAX_COUNT = 100, + + /// The minimum number of apps in a package. + PACKAGE_APPLICATIONS_MIN_COUNT = 0, + + /// The maximum number of resource packages a package can have. + PACKAGE_FAMILY_MAX_RESOURCE_PACKAGES = 512, + + /// The minimum number of resource packages a package can have. + PACKAGE_FAMILY_MIN_RESOURCE_PACKAGES = 0, + + /// + /// Process all packages in the dependency graph. This is equivalent to PACKAGE_FILTER_HEAD | PACKAGE_FILTER_DIRECT. Note: + /// PACKAGE_FILTER_ALL_LOADED may be altered or unavailable for releases after Windows 8.1. Instead, use PACKAGE_FILTER_HEAD | PACKAGE_FILTER_DIRECT. + /// + PACKAGE_FILTER_ALL_LOADED = 0x00000000, + + /// Process bundle packages in the package graph. + PACKAGE_FILTER_BUNDLE = 0x00000080, + + /// Process the directly dependent packages of the head (first) package in the dependency graph. + PACKAGE_FILTER_DIRECT = 0x00000020, + + /// Process the first package in the dependency graph. + PACKAGE_FILTER_HEAD = 0x00000010, + + /// Process bundle packages in the package graph. + PACKAGE_FILTER_OPTIONAL = 0x00020000, + + /// Process resource packages in the package graph. + PACKAGE_FILTER_RESOURCE = 0x00000040, + + /// The maximum size of a package graph. + PACKAGE_GRAPH_MAX_SIZE = (1 + PACKAGE_MAX_DEPENDENCIES + PACKAGE_FAMILY_MAX_RESOURCE_PACKAGES), + + /// The minimum size of a package graph. + PACKAGE_GRAPH_MIN_SIZE = 1, + + /// Retrieve basic information. + PACKAGE_INFORMATION_BASIC = 0x00000000, + + /// Retrieve full information. + PACKAGE_INFORMATION_FULL = 0x00000100, + + /// The maximum number of packages a package depends on. + PACKAGE_MAX_DEPENDENCIES = 128, + + /// The minimum number of packages a package depends on. + PACKAGE_MIN_DEPENDENCIES = 0, + + /// The package is a bundle package. + PACKAGE_PROPERTY_BUNDLE = 0x00000004, + + /// The package was registered with the DeploymentOptions enumeration. + PACKAGE_PROPERTY_DEVELOPMENT_MODE = 0x00010000, + + /// The package is a framework. + PACKAGE_PROPERTY_FRAMEWORK = 0x00000001, + + /// The package is an optional package. + PACKAGE_PROPERTY_OPTIONAL = 0x00000008, + + /// The package is a resource package. + PACKAGE_PROPERTY_RESOURCE = 0x00000002, + } + + /// Specifies values that indicate the type of artifact that is used to define the lifetime of a package dependency. + // https://docs.microsoft.com/en-us/windows/win32/api/appmodel/ne-appmodel-packagedependencylifetimekind typedef enum + // PackageDependencyLifetimeKind { PackageDependencyLifetimeKind_Process, PackageDependencyLifetimeKind_FilePath, + // PackageDependencyLifetimeKind_RegistryKey } ; + [PInvokeData("appmodel.h", MSDNShortId = "NE:appmodel.PackageDependencyLifetimeKind")] + public enum PackageDependencyLifetimeKind + { + /// + /// The current process is the lifetime artifact. The package dependency is implicitly deleted when the process terminates. + /// + PackageDependencyLifetimeKind_Process, + + /// + /// The lifetime artifact is an absolute filename or path. The package dependency is implicitly deleted when this is deleted. + /// + PackageDependencyLifetimeKind_FilePath, + + /// + /// The lifetime artifact is a registry key in the format + /// root + /// \ + /// subkey + /// , where + /// root + /// + /// is one of the following: HKEY_LOCAL_MACHINE, HKEY_CURRENT_USER, HKEY_CLASSES_ROOT, or HKEY_USERS. The package dependency is + /// implicitly deleted when this is deleted. + /// + /// + PackageDependencyLifetimeKind_RegistryKey, + } + + /// + /// Defines the processor architectures for a framework package dependency that you create by using the TryCreatePackageDependency function. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/appmodel/ne-appmodel-packagedependencyprocessorarchitectures typedef enum + // PackageDependencyProcessorArchitectures { PackageDependencyProcessorArchitectures_None, + // PackageDependencyProcessorArchitectures_Neutral, PackageDependencyProcessorArchitectures_X86, + // PackageDependencyProcessorArchitectures_X64, PackageDependencyProcessorArchitectures_Arm, + // PackageDependencyProcessorArchitectures_Arm64, PackageDependencyProcessorArchitectures_X86A64 } ; + [PInvokeData("appmodel.h", MSDNShortId = "NE:appmodel.PackageDependencyProcessorArchitectures")] + [Flags] + public enum PackageDependencyProcessorArchitectures + { + /// No processor architecture is specified. + PackageDependencyProcessorArchitectures_None = 0x0000, + + /// Specifies the neutral architecture. + PackageDependencyProcessorArchitectures_Neutral = 0x0001, + + /// Specifies the x86 architecture. + PackageDependencyProcessorArchitectures_X86 = 0x0002, + + /// Specifies the x64 architecture. + PackageDependencyProcessorArchitectures_X64 = 0x0004, + + /// Specifies the ARM architecture. + PackageDependencyProcessorArchitectures_Arm = 0x0008, + + /// Specifies the ARM64 architecture. + PackageDependencyProcessorArchitectures_Arm64 = 0x0010, + + /// Specifies the x86/A64 architecture. + PackageDependencyProcessorArchitectures_X86A64 = 0x0020, + } + + /// + /// Specifies the origin of a package. + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/ne-appmodel-packageorigin typedef enum PackageOrigin { + // PackageOrigin_Unknown , PackageOrigin_Unsigned , PackageOrigin_Inbox , PackageOrigin_Store , PackageOrigin_DeveloperUnsigned , + // PackageOrigin_DeveloperSigned , PackageOrigin_LineOfBusiness } ; + [PInvokeData("appmodel.h", MSDNShortId = "0CB9CE97-8A54-4BE7-B054-00F29D36CAB2")] + public enum PackageOrigin + { + /// The package's origin is unknown. + PackageOrigin_Unknown, + + /// The package originated as unsigned. + PackageOrigin_Unsigned, + + /// The package was included inbox. + PackageOrigin_Inbox, + + /// The package originated from the Windows Store. + PackageOrigin_Store, + + /// The package originated as developer unsigned. + PackageOrigin_DeveloperUnsigned, + + /// The package originated as developer signed. + PackageOrigin_DeveloperSigned, + + /// The package originated as a line-of-business app. + PackageOrigin_LineOfBusiness, + } + + /// Indicates the type of folder path to retrieve in a query for the path or other info about a package. + /// + /// An application has a mutable install folder if it uses the windows.mutablePackageDirectories extension in its package manifest. + /// This extension specifies a folder under the %ProgramFiles%\ModifiableWindowsApps path where the contents of the application's + /// install folder are projected so that users can modify the installation files. This feature is currently available only for + /// certain types of desktop PC games that are published by Microsoft and our partners, and it enables these types of games to + /// support mods. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/appmodel/ne-appmodel-packagepathtype typedef enum PackagePathType { + // PackagePathType_Install, PackagePathType_Mutable, PackagePathType_Effective } ; + [PInvokeData("appmodel.h")] + public enum PackagePathType + { + /// Retrieve the package path in the original install folder for the application. + PackagePathType_Install, + + /// + /// Retrieve the package path in the mutable install folder for the application, if the application is declared as mutable in + /// the package manifest. + /// + PackagePathType_Mutable, + + /// + /// Retrieve the package path in the mutable folder if the application is declared as mutable in the package manifest, or in the + /// original install folder if the application is not mutable. + /// + PackagePathType_Effective + } + + /// + /// Adds a run-time reference for the framework package dependency you created earlier by using the TryCreatePackageDependency + /// method, with the specified options. After this method successfully returns, your app can activate types and use content from the + /// framework package. + /// + /// + /// Type: PCWSTR + /// + /// The ID of the package dependency to be resolved and added to the invoking process' package graph. This parameter must match a + /// package dependency defined by using the TryCreatePackageDependency function for the calling user or the system (via the + /// CreatePackageDependencyOptions_ScopeIsSystem option), or else an error is returned. + /// + /// + /// + /// Type: INT32 + /// The rank to use to add the resolved package to the caller's package graph. For more information, see the remarks. + /// + /// + /// Type: AddPackageDependencyOptions + /// The options to apply when adding the package dependency. + /// + /// + /// Type: PACKAGEDEPENDENCY_CONTEXT* + /// The handle of the added package dependency. This handle is valid until it is passed to RemovePackageDependency. + /// + /// + /// Type: PCWSTR* + /// + /// The full name of the package to which the dependency has been resolved. Use the HeapAlloc function to allocate memory for this + /// parameter, and use HeapFree to deallocate the memory. + /// + /// + /// + /// Type: HRESULT + /// + /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error + /// codes include the following. + /// + /// + /// + /// Return code + /// Description + /// + /// + /// E_INVALIDARG + /// The packageDependencyId or packageDependencyContext parameter is NULL on input. + /// + /// + /// + /// + /// + /// Calling this method resolves the framework package dependency to a specific package on the system. It also informs the OS that + /// the framework package is in active use and to handle any version updates in a side-by-side manner (effectively delay + /// uninstalling or otherwise servicing the older version until after your app is done using it). Package resolution is specific to + /// a user and can return different values for different users on a system. + /// + /// + /// Each successful AddPackageDependency call adds the resolved package to the calling process' package graph, even if + /// already present. There is no duplicate detection or filtering applied by the API (that is, multiple references from a package is + /// not harmful). After resolution is complete, the package dependency stays resolved for that user until the last reference across + /// all processes for that user is removed via RemovePackageDependency or the process is terminated. + /// + /// + /// After this method successfully returns, your app can activate types and use content from the framework package until + /// RemovePackageDependency is called. + /// + /// + /// If multiple packages are present in the package graph with the same rank as the call to AddPackageDependency, the + /// resolved package is (by default) added after others of the same rank. To add a package before others of the same rank, specify + /// AddPackageDependencyOptions_PrependIfRankCollision for the options parameter. + /// + /// For more information, see Use the dynamic dependency API to reference framework packages at run time. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/appmodel/nf-appmodel-addpackagedependency HRESULT AddPackageDependency( PCWSTR + // packageDependencyId, INT32 rank, AddPackageDependencyOptions options, PACKAGEDEPENDENCY_CONTEXT *packageDependencyContext, PWSTR + // *packageFullName ); + [DllImport(Lib.KernelBase, SetLastError = false, ExactSpelling = true)] + [PInvokeData("appmodel.h", MSDNShortId = "NF:appmodel.AddPackageDependency")] + public static extern HRESULT AddPackageDependency([MarshalAs(UnmanagedType.LPWStr)] string packageDependencyId, int rank, + AddPackageDependencyOptions options, out PACKAGEDEPENDENCY_CONTEXT packageDependencyContext, out SafeHeapBlock packageFullName); + + /// + /// Retrieves a value indicating whether a process has full or restricted access to the IO devices (file, file stream, directory, + /// physical disk, volume, console buffer, tape drive, communications resource, mailslot, and pipe). + /// + /// A handle that identifies the access token for a process. + /// + /// A pointer to a variable of the AppPolicyCreateFileAccess enumerated type. When the function returns successfully, the + /// variable contains an enumerated constant value indicating whether the process has full or restricted access to the IO devices. + /// + /// + /// If the function succeeds, the function returns ERROR_SUCCESS. + /// + /// If no known create file access policy was found for the process token, the function raises a STATUS_ASSERTION_FAILURE exception + /// and returns ERROR_NOT_FOUND. + /// + /// If either processToken or policy are null, the function returns ERROR_INVALID_PARAMETER. + /// + // LONG WINAPI AppPolicyGetCreateFileAccess( _In_ HANDLE processToken, _Out_ AppPolicyCreateFileAccess *policy); https://msdn.microsoft.com/en-us/library/windows/desktop/mt829655(v=vs.85).aspx + [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true)] + [PInvokeData("AppModel.h", MSDNShortId = "mt829655")] + public static extern Win32Error AppPolicyGetCreateFileAccess(HTOKEN processToken, out AppPolicyCreateFileAccess policy); + + /// Retrieves the method used to end a process. + /// A handle that identifies the access token for a process. + /// + /// A pointer to a variable of the AppPolicyProcessTerminationMethod enumerated type. When the function returns successfully, + /// the variable contains a value indicating the method used to end the process. + /// + /// + /// If the function succeeds, the function returns ERROR_SUCCESS. + /// + /// If no known create file access policy was found for the process token, the function raises a STATUS_ASSERTION_FAILURE exception + /// and returns ERROR_NOT_FOUND. + /// + /// If either processToken or policy are null, the function returns ERROR_INVALID_PARAMETER. + /// + // LONG WINAPI AppPolicyGetProcessTerminationMethod( _In_ HANDLE processToken, _Out_ AppPolicyProcessTerminationMethod *policy); https://msdn.microsoft.com/en-us/library/windows/desktop/mt829656(v=vs.85).aspx + [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true)] + [PInvokeData("AppModel.h", MSDNShortId = "mt829656")] + public static extern Win32Error AppPolicyGetProcessTerminationMethod(HTOKEN processToken, out AppPolicyProcessTerminationMethod policy); + + /// Retrieves the method used for a process to surface developer information, such as asserts, to the user. + /// A handle that identifies the access token for a process. + /// + /// A pointer to a variable of the AppPolicyShowDeveloperDiagnostic enumerated type. When the function returns successfully, + /// the variable contains a value indicating the method used for the process to surface developer information, such as asserts, to + /// the user. + /// + /// + /// If the function succeeds, the function returns ERROR_SUCCESS. + /// + /// If no known create file access policy was found for the process token, the function raises a STATUS_ASSERTION_FAILURE exception + /// and returns ERROR_NOT_FOUND. + /// + /// If either processToken or policy are null, the function returns ERROR_INVALID_PARAMETER. + /// + // LONG WINAPI AppPolicyGetShowDeveloperDiagnostic( _In_ HANDLE processToken, _Out_ AppPolicyShowDeveloperDiagnostic *policy); https://msdn.microsoft.com/en-us/library/windows/desktop/mt829657(v=vs.85).aspx + [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true)] + [PInvokeData("AppModel.h", MSDNShortId = "mt829657")] + public static extern Win32Error AppPolicyGetShowDeveloperDiagnostic(HTOKEN processToken, out AppPolicyShowDeveloperDiagnostic policy); + + /// + /// Retrieves the kind of initialization that should be automatically performed for a process when beginthread[ex] creates a thread. + /// + /// A handle that identifies the access token for a process. + /// + /// A pointer to a variable of the AppPolicyThreadInitializationType enumerated type. When the function returns successfully, + /// the variable contains a value indicating the kind of initialization that should be automatically performed for the process when + /// beginthread[ex] creates a thread. + /// + /// + /// If the function succeeds, the function returns ERROR_SUCCESS. + /// + /// If no known create file access policy was found for the process token, the function raises a STATUS_ASSERTION_FAILURE exception + /// and returns ERROR_NOT_FOUND. + /// + /// If either processToken or policy are null, the function returns ERROR_INVALID_PARAMETER. + /// + // LONG WINAPI AppPolicyGetThreadInitializationType( _In_ HANDLE processToken, _Out_ AppPolicyThreadInitializationType *policy); https://msdn.microsoft.com/en-us/library/windows/desktop/mt829658(v=vs.85).aspx + [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true)] + [PInvokeData("AppModel.h", MSDNShortId = "mt829658")] + public static extern Win32Error AppPolicyGetThreadInitializationType(HTOKEN processToken, out AppPolicyThreadInitializationType policy); + + /// + /// Closes a reference to the specified package information. + /// + /// + /// Type: PACKAGE_INFO_REFERENCE + /// A reference to package information. + /// + /// + /// Type: LONG + /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-closepackageinfo LONG ClosePackageInfo( + // PACKAGE_INFO_REFERENCE packageInfoReference ); + [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true)] + [PInvokeData("appmodel.h", MSDNShortId = "BA84FB47-F241-4120-9441-7E1149F68738")] + public static extern Win32Error ClosePackageInfo(PACKAGE_INFO_REFERENCE packageInfoReference); + + /// + /// Deletes the install-time reference for the framework package dependency you created earlier by using the + /// TryCreatePackageDependency method. This method informs the OS that it is safe to remove the framework package if no other apps + /// have a dependency on it. + /// + /// + /// Type: PCWSTR + /// The ID of the package dependency to remove. + /// + /// + /// + /// + /// Return code + /// Description + /// + /// + /// E_INVALIDARG + /// The packageDependencyId parameter is NULL on input. + /// + /// + /// + /// + /// + /// Removing a package dependency is typically done when an app is uninstalled. A package dependency is implicitly removed if its + /// lifetime artifact (specified via the lifetimeArtifact parameter of the TryCreatePackageDependency function) is deleted. Package + /// dependencies that are not referenced by other packages are elegible to be removed. + /// + /// The caller of this function must have administrative privileges if the package dependency was created using CreatePackageDependencyOptions_ScopeIsSystem. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/appmodel/nf-appmodel-deletepackagedependency + // HRESULT DeletePackageDependency( PCWSTR packageDependencyId ); + [DllImport(Lib.KernelBase, SetLastError = false, ExactSpelling = true)] + [PInvokeData("appmodel.h", MSDNShortId = "NF:appmodel.DeletePackageDependency")] + public static extern HRESULT DeletePackageDependency([MarshalAs(UnmanagedType.LPWStr)] string packageDependencyId); + + /// + /// Finds the packages with the specified family name for the current user. + /// + /// + /// Type: PCWSTR + /// The package family name. + /// + /// + /// Type: UINT32 + /// + /// The package constants that specify how package information is retrieved. All package constants except + /// PACKAGE_FILTER_ALL_LOADED are supported. + /// + /// + /// + /// Type: UINT32* + /// A pointer to a variable that holds the number of package full names that were found. + /// + /// First you pass NULL to packageFullNames to get the number of package full names that were found. You use this number to + /// allocate memory space for packageFullNames. Then you pass the address of this memory space to fill packageFullNames. + /// + /// + /// + /// Type: PWSTR* + /// A pointer to memory space that receives the strings of package full names that were found. + /// + /// + /// Type: UINT32* + /// A pointer to a variable that holds the number of characters in the string of package full names. + /// + /// First you pass NULL to buffer to get the number of characters. You use this number to allocate memory space for buffer. + /// Then you pass the address of this memory space to fill buffer. + /// + /// + /// + /// Type: WCHAR* + /// A pointer to memory space that receives the string of characters for all of the package full names. + /// + /// + /// Type: UINT32* + /// A pointer to memory space that receives the package properties for all of the packages that were found. + /// + /// + /// Type: LONG + /// + /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error + /// codes include the following. + /// + /// + /// + /// Return code + /// Description + /// + /// + /// ERROR_INSUFFICIENT_BUFFER + /// One or more buffer is not large enough to hold the data. The required size is specified by either count or buffer. + /// + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-findpackagesbypackagefamily LONG + // FindPackagesByPackageFamily( PCWSTR packageFamilyName, UINT32 packageFilters, UINT32 *count, PWSTR *packageFullNames, UINT32 + // *bufferLength, WCHAR *buffer, UINT32 *packageProperties ); + [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true, CharSet = CharSet.Unicode)] + [PInvokeData("appmodel.h", MSDNShortId = "D52E98BD-726F-4AC0-A034-02896B1D1687")] + public static extern Win32Error FindPackagesByPackageFamily(string packageFamilyName, PACKAGE_FLAGS packageFilters, ref uint count, IntPtr packageFullNames, ref uint bufferLength, IntPtr buffer, IntPtr packageProperties); + + /// Finds the packages with the specified family name for the current user. + /// Type: PCWSTR + /// The package family name. + /// Type: UINT32 + /// + /// The package constants that specify how package information is retrieved. All package constants except + /// PACKAGE_FILTER_ALL_LOADED are supported. + /// + /// Type: PWSTR* + /// Receives the strings of package full names that were found. + /// Type: UINT32* + /// Receives the package properties for all of the packages that were found. + /// + /// Type: LONG + /// + /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-findpackagesbypackagefamily LONG + // FindPackagesByPackageFamily( PCWSTR packageFamilyName, UINT32 packageFilters, UINT32 *count, PWSTR *packageFullNames, UINT32 + // *bufferLength, WCHAR *buffer, UINT32 *packageProperties ); + [PInvokeData("appmodel.h", MSDNShortId = "D52E98BD-726F-4AC0-A034-02896B1D1687")] + public static Win32Error FindPackagesByPackageFamily(string packageFamilyName, PACKAGE_FLAGS packageFilters, out string?[] packageFullNames, out uint[] packageProperties) + { + uint count = 0, bufferLength = 0; + packageFullNames = new string[0]; + packageProperties = new uint[0]; + Win32Error err = FindPackagesByPackageFamily(packageFamilyName, packageFilters, ref count, default, ref bufferLength, default, default); + if (count == 0 || err != Win32Error.ERROR_INSUFFICIENT_BUFFER) + return err; + + using InteropServices.SafeCoTaskMemHandle mem = new(count * IntPtr.Size + bufferLength * StringHelper.GetCharSize(CharSet.Unicode) + count * sizeof(uint)); + IntPtr buffer = mem.DangerousGetHandle().Offset(count * IntPtr.Size); + IntPtr props = mem.DangerousGetHandle().Offset(count * IntPtr.Size + bufferLength * StringHelper.GetCharSize(CharSet.Unicode)); + err = FindPackagesByPackageFamily(packageFamilyName, packageFilters, ref count, mem, ref bufferLength, buffer, props); + if (err.Succeeded) { - /// Indicates that the process does not show developer diagnostics. This value is expected for a UWP app. - AppPolicyShowDeveloperDiagnostic_None, - - /// - /// Indicates that the process shows developer diagnostics UI. This value is expected for a desktop application, or for a - /// Desktop Bridge application. - /// - AppPolicyShowDeveloperDiagnostic_ShowUI, + packageFullNames = mem.ToStringEnum((int)count, CharSet.Unicode).ToArray(); + packageProperties = props.ToArray((int)count)!; } + return err; + } + + /// + /// Constructs an application user model ID from the package family name and the package relative application ID (PRAID). + /// + /// + /// Type: PCWSTR + /// The package family name. + /// + /// + /// Type: PCWSTR + /// The package-relative app ID (PRAID). + /// + /// + /// Type: UINT32* + /// + /// A pointer to a variable that holds the number of characters ( WCHAR s) in the app user model ID string, which includes + /// the null-terminator. + /// + /// + /// First you pass NULL to applicationUserModelId to get the number of characters. You use this number to allocate memory + /// space for applicationUserModelId. Then you pass the address of this memory space to fill applicationUserModelId. + /// + /// + /// + /// Type: PWSTR + /// A pointer to memory space that receives the app user model ID string, which includes the null-terminator. + /// + /// + /// Type: LONG + /// + /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error + /// codes include the following. + /// + /// + /// + /// Return code + /// Description + /// + /// + /// ERROR_INVALID_PARAMETER + /// The packageFamilyName or packageRelativeApplicationId parameter isn't valid. + /// + /// + /// ERROR_INSUFFICIENT_BUFFER + /// + /// The buffer specified by applicationUserModelId is not large enough to hold the data; the required buffer size, in WCHARs, is + /// stored in the variable pointed to by applicationUserModelIdLength. + /// + /// + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-formatapplicationusermodelid LONG + // FormatApplicationUserModelId( PCWSTR packageFamilyName, PCWSTR packageRelativeApplicationId, UINT32 + // *applicationUserModelIdLength, PWSTR applicationUserModelId ); + [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true, CharSet = CharSet.Unicode)] + [PInvokeData("appmodel.h", MSDNShortId = "F48D19C2-6373-41FC-A99D-E3CCB68D6C6C")] + public static extern Win32Error FormatApplicationUserModelId(string packageFamilyName, string packageRelativeApplicationId, + ref uint applicationUserModelIdLength, [Optional] StringBuilder? applicationUserModelId); + + /// + /// Gets the application user model ID for the specified process. + /// + /// + /// + /// A handle to the process. This handle must have the PROCESS_QUERY_LIMITED_INFORMATION access right. For more info, see + /// Process Security and Access Rights. + /// + /// + /// + /// + /// On input, the size of the applicationUserModelId buffer, in wide characters. On success, the size of the buffer used, including + /// the null terminator. + /// + /// + /// + /// A pointer to a buffer that receives the application user model ID. + /// + /// + /// + /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error + /// codes include the following. + /// + /// + /// + /// Return code + /// Description + /// + /// + /// APPMODEL_ERROR_NO_APPLICATION + /// The process has no application identity. + /// + /// + /// ERROR_INSUFFICIENT_BUFFER + /// The buffer is not large enough to hold the data. The required size is specified by applicationUserModelIdLength. + /// + /// + /// + /// + /// For info about string size limits, see Identity constants. + /// Examples + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-getapplicationusermodelid LONG + // GetApplicationUserModelId( HANDLE hProcess, UINT32 *applicationUserModelIdLength, PWSTR applicationUserModelId ); + [DllImport(Lib.Kernel32, SetLastError = true, ExactSpelling = true)] + [PInvokeData("appmodel.h", MSDNShortId = "FE4E0818-F548-494B-B3BD-FB51DC748451")] + public static extern Win32Error GetApplicationUserModelId(HPROCESS hProcess, ref uint applicationUserModelIdLength, + [Optional, MarshalAs(UnmanagedType.LPWStr)] StringBuilder? applicationUserModelId); + + /// + /// Gets the application user model ID for the specified token. + /// + /// + /// + /// A token that contains the application identity. This handle must have the PROCESS_QUERY_LIMITED_INFORMATION access right. + /// For more info, see Process Security and Access Rights. + /// + /// + /// + /// + /// On input, the size of the applicationUserModelId buffer, in wide characters. On success, the size of the buffer used, including + /// the null terminator. + /// + /// + /// + /// A pointer to a buffer that receives the application user model ID. + /// + /// + /// + /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error + /// codes include the following. + /// + /// + /// + /// Return code + /// Description + /// + /// + /// APPMODEL_ERROR_NO_APPLICATION + /// The token has no application identity. + /// + /// + /// ERROR_INSUFFICIENT_BUFFER + /// The buffer is not large enough to hold the data. The required size is specified by applicationUserModelIdLength. + /// + /// + /// + /// + /// For info about string size limits, see Identity constants. + /// Examples + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-getapplicationusermodelidfromtoken LONG + // GetApplicationUserModelIdFromToken( HANDLE token, UINT32 *applicationUserModelIdLength, PWSTR applicationUserModelId ); + [DllImport(Lib.KernelBase, SetLastError = true, ExactSpelling = true)] + [PInvokeData("appmodel.h", MSDNShortId = "80036518-927E-4CD0-B499-8EA472AB7E5A")] + public static extern Win32Error GetApplicationUserModelIdFromToken(HTOKEN token, ref uint applicationUserModelIdLength, + [Optional, MarshalAs(UnmanagedType.LPWStr)] StringBuilder? applicationUserModelId); + + /// + /// Gets the application user model ID for the current process. + /// + /// + /// + /// On input, the size of the applicationUserModelId buffer, in wide characters. On success, the size of the buffer used, including + /// the null terminator. + /// + /// + /// + /// A pointer to a buffer that receives the application user model ID. + /// + /// + /// + /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error + /// codes include the following. + /// + /// + /// + /// Return code + /// Description + /// + /// + /// APPMODEL_ERROR_NO_APPLICATION + /// The process has no application identity. + /// + /// + /// ERROR_INSUFFICIENT_BUFFER + /// The buffer is not large enough to hold the data. The required size is specified by applicationUserModelIdLength. + /// + /// + /// + /// + /// For info about string size limits, see Identity constants. + /// Examples + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-getcurrentapplicationusermodelid LONG + // GetCurrentApplicationUserModelId( UINT32 *applicationUserModelIdLength, PWSTR applicationUserModelId ); + [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true, CharSet = CharSet.Unicode)] + [PInvokeData("appmodel.h", MSDNShortId = "562BB225-0922-4FE7-92C0-573A2CCE3195")] + public static extern Win32Error GetCurrentApplicationUserModelId(ref uint applicationUserModelIdLength, [Optional] StringBuilder? applicationUserModelId); + + /// + /// Gets the package family name for the calling process. + /// + /// + /// Type: UINT32* + /// + /// On input, the size of the packageFamilyName buffer, in characters, including the null terminator. On output, the size of the + /// package family name returned, in characters, including the null terminator. + /// + /// + /// + /// Type: PWSTR + /// The package family name. + /// + /// + /// Type: LONG + /// + /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error + /// codes include the following. + /// + /// + /// + /// Return code + /// Description + /// + /// + /// APPMODEL_ERROR_NO_PACKAGE + /// The process has no package identity. + /// + /// + /// ERROR_INSUFFICIENT_BUFFER + /// The buffer is not large enough to hold the data. The required size is specified by packageFamilyNameLength. + /// + /// + /// + /// + /// For info about string size limits, see Identity constants. + /// Examples + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-getcurrentpackagefamilyname LONG + // GetCurrentPackageFamilyName( UINT32 *packageFamilyNameLength, PWSTR packageFamilyName ); + [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true, CharSet = CharSet.Unicode)] + [PInvokeData("appmodel.h", MSDNShortId = "39DBFBDD-A1CC-45C3-A5DD-5ED9697F9AFE")] + public static extern Win32Error GetCurrentPackageFamilyName(ref uint packageFamilyNameLength, [Optional] StringBuilder? packageFamilyName); + + /// + /// Gets the package full name for the calling process. + /// + /// + /// Type: UINT32* + /// + /// On input, the size of the packageFullName buffer, in characters. On output, the size of the package full name returned, in + /// characters, including the null terminator. + /// + /// + /// + /// Type: PWSTR + /// The package full name. + /// + /// + /// Type: LONG + /// + /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error + /// codes include the following. + /// + /// + /// + /// Return code + /// Description + /// + /// + /// APPMODEL_ERROR_NO_PACKAGE + /// The process has no package identity. + /// + /// + /// ERROR_INSUFFICIENT_BUFFER + /// The buffer is not large enough to hold the data. The required size is specified by packageFullNameLength. + /// + /// + /// + /// + /// For info about string size limits, see Identity constants. + /// Examples + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-getcurrentpackagefullname LONG + // GetCurrentPackageFullName( UINT32 *packageFullNameLength, PWSTR packageFullName ); + [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true, CharSet = CharSet.Unicode)] + [PInvokeData("appmodel.h", MSDNShortId = "D5B00C53-1FBF-4245-92D1-FA39713A9EE7")] + public static extern Win32Error GetCurrentPackageFullName(ref uint packageFullNameLength, [Optional] StringBuilder? packageFullName); + + /// + /// Gets the package identifier (ID) for the calling process. + /// + /// + /// Type: UINT32* + /// On input, the size of buffer, in bytes. On output, the size of the structure returned, in bytes. + /// + /// + /// Type: BYTE* + /// The package ID, represented as a PACKAGE_ID structure. + /// + /// + /// Type: LONG + /// + /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error + /// codes include the following. + /// + /// + /// + /// Return code + /// Description + /// + /// + /// APPMODEL_ERROR_NO_PACKAGE + /// The process has no package identity. + /// + /// + /// ERROR_INSUFFICIENT_BUFFER + /// The buffer is not large enough to hold the data. The required size is specified by bufferLength. + /// + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-getcurrentpackageid LONG GetCurrentPackageId( UINT32 + // *bufferLength, BYTE *buffer ); + [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true)] + [PInvokeData("appmodel.h", MSDNShortId = "4CFC707A-2A5A-41FE-BB5F-6FECACC99271")] + public static extern Win32Error GetCurrentPackageId(ref uint bufferLength, IntPtr buffer); + + /// + /// Gets the package information for the calling process. + /// + /// + /// Type: const UINT32 + /// The package constants that specify how package information is retrieved. The PACKAGE_FILTER_* flags are supported. + /// + /// + /// Type: UINT32* + /// On input, the size of buffer, in bytes. On output, the size of the array of structures returned, in bytes. + /// + /// + /// Type: BYTE* + /// The package information, represented as an array of PACKAGE_INFO structures. + /// + /// + /// Type: UINT32* + /// The number of structures in the buffer. + /// + /// + /// Type: LONG + /// + /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error + /// codes include the following. + /// + /// + /// + /// Return code + /// Description + /// + /// + /// APPMODEL_ERROR_NO_PACKAGE + /// The process has no package identity. + /// + /// + /// ERROR_INSUFFICIENT_BUFFER + /// The buffer is not large enough to hold the data. The required size is specified by bufferLength. + /// + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-getcurrentpackageinfo LONG GetCurrentPackageInfo( const + // UINT32 flags, UINT32 *bufferLength, BYTE *buffer, UINT32 *count ); + [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true)] + [PInvokeData("appmodel.h", MSDNShortId = "A1887D61-0FAD-4BE8-850F-F104CC074798")] + public static extern Win32Error GetCurrentPackageInfo(PACKAGE_FLAGS flags, ref uint bufferLength, IntPtr buffer, out uint count); + + /// + /// Gets the package information for the calling process, with the option to specify the type of folder path to retrieve for the package. + /// + /// + /// Type: const UINT32 + /// The package constants that specify how package information is retrieved. The PACKAGE_FILTER_* flags are supported. + /// + /// + /// Type: PackagePathType + /// Indicates the type of folder path to retrieve for the package (the original install folder or the mutable folder). + /// + /// + /// Type: UINT32* + /// On input, the size of buffer, in bytes. On output, the size of the array of structures returned, in bytes. + /// + /// + /// Type: BYTE* + /// The package information, represented as an array of PACKAGE_INFO structures. + /// + /// + /// Type: UINT32* + /// The number of structures in the buffer. + /// + /// + /// Type: LONG + /// + /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error + /// codes include the following. + /// + /// + /// + /// Return code + /// Description + /// + /// + /// APPMODEL_ERROR_NO_PACKAGE + /// The process has no package identity. + /// + /// + /// ERROR_INSUFFICIENT_BUFFER + /// The buffer is not large enough to hold the data. The required size is specified by bufferLength. + /// + /// + /// + /// + /// The packagePathType parameter is useful for applications that use the windows.mutablePackageDirectories extension in their + /// package manifest. This extension specifies a folder under the %ProgramFiles%\ModifiableWindowsApps path where the contents of + /// the application's install folder are projected so that users can modify the installation files. This feature is currently + /// available only for certain types of desktop PC games that are published by Microsoft and our partners, and it enables these + /// types of games to support mods. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/appmodel/nf-appmodel-getcurrentpackageinfo2 LONG GetCurrentPackageInfo2( const + // UINT32 flags, PackagePathType packagePathType, UINT32 *bufferLength, BYTE *buffer, UINT32 *count ); + [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true)] + [PInvokeData("appmodel.h")] + public static extern Win32Error GetCurrentPackageInfo2(PACKAGE_FLAGS flags, PackagePathType packagePathType, ref uint bufferLength, IntPtr buffer, out uint count); + + /// + /// Gets the package path for the calling process. + /// + /// + /// Type: UINT32* + /// + /// On input, the size of the path buffer, in characters. On output, the size of the package path returned, in characters, including + /// the null terminator. + /// + /// + /// + /// Type: PWSTR + /// The package path. + /// + /// + /// Type: LONG + /// + /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error + /// codes include the following. + /// + /// + /// + /// Return code + /// Description + /// + /// + /// APPMODEL_ERROR_NO_PACKAGE + /// The process has no package identity. + /// + /// + /// ERROR_INSUFFICIENT_BUFFER + /// The buffer is not large enough to hold the data. The required size is specified by pathLength. + /// + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-getcurrentpackagepath LONG GetCurrentPackagePath( UINT32 + // *pathLength, PWSTR path ); + [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true, CharSet = CharSet.Unicode)] + [PInvokeData("appmodel.h", MSDNShortId = "46CE81DF-A9D5-492E-AB5E-4F043DC326E2")] + public static extern Win32Error GetCurrentPackagePath(ref uint pathLength, [Optional] StringBuilder? path); + + /// + /// Gets the package path for the calling process, with the option to specify the type of folder path to retrieve for the package. + /// + /// + /// Type: PackagePathType + /// Indicates the type of folder path to retrieve for the package (the original install folder or the mutable folder). + /// + /// + /// Type: UINT32* + /// + /// On input, the size of the path buffer, in characters. On output, the size of the package path returned, in characters, including + /// the null terminator. + /// + /// + /// + /// Type: PWSTR + /// The package path. + /// + /// + /// Type: LONG + /// + /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error + /// codes include the following. + /// + /// + /// + /// Return code + /// Description + /// + /// + /// APPMODEL_ERROR_NO_PACKAGE + /// The process has no package identity. + /// + /// + /// ERROR_INSUFFICIENT_BUFFER + /// The buffer is not large enough to hold the data. The required size is specified by pathLength. + /// + /// + /// + /// + /// The packagePathType parameter is useful for applications that use the windows.mutablePackageDirectories extension in their + /// package manifest. This extension specifies a folder under the %ProgramFiles%\ModifiableWindowsApps path where the contents of + /// the application's install folder are projected so that users can modify the installation files. This feature is currently + /// available only for certain types of desktop PC games that are published by Microsoft and our partners, and it enables these + /// types of games to support mods. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/appmodel/nf-appmodel-getcurrentpackagepath2 LONG GetCurrentPackagePath2( + // PackagePathType packagePathType, UINT32 *pathLength, PWSTR path ); + [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true)] + [PInvokeData("appmodel.h")] + public static extern Win32Error GetCurrentPackagePath2(PackagePathType packagePathType, ref uint pathLength, + [Optional, MarshalAs(UnmanagedType.LPWStr)] StringBuilder? path); + + /// Returns the package dependency for the specified context handle. + /// + /// Type: PACKAGEDEPENDENCY_CONTEXT + /// The handle of the package dependency to return. + /// + /// + /// Type: PCWSTR* + /// + /// The ID of the package dependency for the specified context handle. If the package dependency cannot be resolved, the function + /// succeeds but this parameter is nullptr on output. Use the HeapAlloc function to allocate memory for this parameter, and + /// use HeapFree to deallocate the memory. + /// + /// + /// + /// + /// + /// Return code + /// Description + /// + /// + /// E_INVALIDARG + /// The packageDependencyContext or packageDependencyId parameter is NULL on input. + /// + /// + /// + // https://docs.microsoft.com/gl-es/windows/win32/api/appmodel/nf-appmodel-getidforpackagedependencycontext + // HRESULT GetIdForPackageDependencyContext( PACKAGEDEPENDENCY_CONTEXT packageDependencyContext, PWSTR *packageDependencyId ); + [DllImport(Lib.KernelBase, SetLastError = false, ExactSpelling = true)] + [PInvokeData("appmodel.h", MSDNShortId = "NF:appmodel.GetIdForPackageDependencyContext")] + public static extern HRESULT GetIdForPackageDependencyContext(PACKAGEDEPENDENCY_CONTEXT packageDependencyContext, + out SafeHeapBlock packageDependencyId); + + /// + /// Gets the IDs of apps in the specified package. + /// + /// + /// Type: PACKAGE_INFO_REFERENCE + /// A reference to package information. + /// + /// + /// Type: UINT32* + /// A pointer to a variable that holds the size of buffer, in bytes. + /// + /// First you pass NULL to buffer to get the required size of buffer. You use this number to allocate memory space for + /// buffer. Then you pass the address of this memory space to fill buffer. + /// + /// + /// + /// Type: BYTE* + /// A pointer to memory space that receives the app IDs. + /// + /// + /// Type: UINT32* + /// A pointer to a variable that receives the number of app IDs in buffer. + /// + /// + /// Type: LONG + /// + /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error + /// codes include the following. + /// + /// + /// + /// Return code + /// Description + /// + /// + /// ERROR_INSUFFICIENT_BUFFER + /// The buffer is not large enough to hold the data. The required size is specified by bufferLength. + /// + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-getpackageapplicationids LONG GetPackageApplicationIds( + // PACKAGE_INFO_REFERENCE packageInfoReference, UINT32 *bufferLength, BYTE *buffer, UINT32 *count ); + [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true)] + [PInvokeData("appmodel.h", MSDNShortId = "F08135F9-FF45-4309-84B5-77F4AFD7FC0C")] + public static extern Win32Error GetPackageApplicationIds(PACKAGE_INFO_REFERENCE packageInfoReference, ref uint bufferLength, IntPtr buffer, out uint count); + + /// + /// Gets the package family name for the specified process. + /// + /// + /// Type: HANDLE + /// + /// A handle to the process that has the PROCESS_QUERY_INFORMATION or PROCESS_QUERY_LIMITED_INFORMATION access right. + /// For more information, see Process Security and Access Rights. + /// + /// + /// + /// Type: UINT32* + /// + /// On input, the size of the packageFamilyName buffer, in characters. On output, the size of the package family name returned, in + /// characters, including the null-terminator. + /// + /// + /// + /// Type: PWSTR + /// The package family name. + /// + /// + /// Type: LONG + /// + /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error + /// codes include the following. + /// + /// + /// + /// Return code + /// Description + /// + /// + /// APPMODEL_ERROR_NO_PACKAGE + /// The process has no package identity. + /// + /// + /// ERROR_INSUFFICIENT_BUFFER + /// The buffer is not large enough to hold the data. The required size is specified by packageFamilyNameLength. + /// + /// + /// + /// + /// For info about string size limits, see Identity constants. + /// Examples + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-getpackagefamilyname LONG GetPackageFamilyName( HANDLE + // hProcess, UINT32 *packageFamilyNameLength, PWSTR packageFamilyName ); + [DllImport(Lib.Kernel32, SetLastError = true, ExactSpelling = true, CharSet = CharSet.Unicode)] + [PInvokeData("appmodel.h", MSDNShortId = "AC239898-9924-4193-9072-7A7EEC2D03E9")] + public static extern Win32Error GetPackageFamilyName(HPROCESS hProcess, ref uint packageFamilyNameLength, [Optional] StringBuilder? packageFamilyName); + + /// + /// Gets the package family name for the specified token. + /// + /// + /// Type: HANDLE + /// A token that contains the package identity. + /// + /// + /// Type: UINT32* + /// + /// On input, the size of the packageFamilyName buffer, in characters. On output, the size of the package family name returned, in + /// characters, including the null-terminator. + /// + /// + /// + /// Type: PWSTR + /// The package family name. + /// + /// + /// Type: LONG + /// + /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error + /// codes include the following. + /// + /// + /// + /// Return code + /// Description + /// + /// + /// APPMODEL_ERROR_NO_PACKAGE + /// The token has no package identity. + /// + /// + /// ERROR_INSUFFICIENT_BUFFER + /// The buffer is not large enough to hold the data. The required size is specified by packageFamilyNameLength. + /// + /// + /// + /// + /// For info about string size limits, see Identity constants. + /// Examples + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-getpackagefamilynamefromtoken LONG + // GetPackageFamilyNameFromToken( HANDLE token, UINT32 *packageFamilyNameLength, PWSTR packageFamilyName ); + [DllImport(Lib.KernelBase, SetLastError = true, ExactSpelling = true, CharSet = CharSet.Unicode)] + [PInvokeData("appmodel.h", MSDNShortId = "C4FAF5DE-DF1F-4AFA-813B-5D80C786031B")] + public static extern Win32Error GetPackageFamilyNameFromToken(HTOKEN token, ref uint packageFamilyNameLength, [Optional] StringBuilder? packageFamilyName); + + /// Gets the package full name for the specified process. + /// + /// Type: HANDLE + /// + /// A handle to the process that has the PROCESS_QUERY_INFORMATION or PROCESS_QUERY_LIMITED_INFORMATION access right. + /// For more information, see Process Security and Access Rights. + /// + /// + /// + /// Type: UINT32* + /// + /// On input, the size of the packageFullName buffer, in characters. On output, the size of the package full name returned, in + /// characters, including the null terminator. + /// + /// + /// + /// Type: PWSTR + /// The package full name. + /// + /// + /// Type: LONG + /// + /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error + /// codes include the following. + /// + /// + /// + /// Return code + /// Description + /// + /// + /// APPMODEL_ERROR_NO_PACKAGE + /// The process has no package identity. + /// + /// + /// ERROR_INSUFFICIENT_BUFFER + /// The buffer is not large enough to hold the data. The required size is specified by packageFullNameLength. + /// + /// + /// + /// + /// For info about string size limits, see Identity constants. + /// Examples + /// + /// #define _UNICODE 1 #define UNICODE 1 #include <Windows.h> #include <appmodel.h> #include <malloc.h> #include <stdlib.h> #include <stdio.h> int ShowUsage(); void ShowProcessPackageFullName(__in const UINT32 pid, __in HANDLE process); int ShowUsage() { wprintf(L"Usage: GetPackageFullName <pid> [<pid>...]\n"); return 1; } int __cdecl wmain(__in int argc, __in_ecount(argc) WCHAR * argv[]) { if (argc <= 1) return ShowUsage(); for (int i=1; i<argc; ++i) { UINT32 pid = wcstoul(argv[i], NULL, 10); if (pid > 0) { HANDLE process = OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION, FALSE, pid); if (process == NULL) wprintf(L"Error %d in OpenProcess (pid=%u)\n", GetLastError(), pid); else { ShowProcessPackageFullName(pid, process); CloseHandle(process); } } } return 0; } void ShowProcessPackageFullName(__in const UINT32 pid, __in HANDLE process) { wprintf(L"Process %u (handle=%p)\n", pid, process); UINT32 length = 0; LONG rc = GetPackageFullName(process, &length, NULL); if (rc != ERROR_INSUFFICIENT_BUFFER) { if (rc == APPMODEL_ERROR_NO_PACKAGE) wprintf(L"Process has no package identity\n"); else wprintf(L"Error %d in GetPackageFullName\n", rc); return; } PWSTR fullName = (PWSTR) malloc(length * sizeof(*fullName)); if (fullName == NULL) { wprintf(L"Error allocating memory\n"); return; } rc = GetPackageFullName(process, &length, fullName); if (rc != ERROR_SUCCESS) wprintf(L"Error %d retrieving PackageFullName\n", rc); else wprintf(L"%s\n", fullName); free(fullName); } + /// + /// + // https://webcache.googleusercontent.com/search?q=cache:IqzT6kD4rycJ:https://docs.microsoft.com/en-us/windows/win32/api/appmodel/nf-appmodel-getpackagefullname+&cd=2&hl=en&ct=clnk&gl=us + // LONG GetPackageFullName( HANDLE hProcess, UINT32 *packageFullNameLength, PWSTR packageFullName ); + [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true)] + [PInvokeData("appmodel.h", MSDNShortId = "NF:appmodel.GetPackageFullName")] + public static extern Win32Error GetPackageFullName(HPROCESS hProcess, ref uint packageFullNameLength, + [Optional, MarshalAs(UnmanagedType.LPWStr)] StringBuilder? packageFullName); + + /// + /// Gets the package full name for the specified token. + /// + /// + /// A token that contains the package identity. + /// + /// + /// + /// On input, the size of the packageFullName buffer, in characters. On output, the size of the package full name returned, in + /// characters, including the null terminator. + /// + /// + /// + /// The package full name. + /// + /// + /// + /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error + /// codes include the following. + /// + /// + /// + /// Return code + /// Description + /// + /// + /// APPMODEL_ERROR_NO_PACKAGE + /// The token has no package identity. + /// + /// + /// ERROR_INSUFFICIENT_BUFFER + /// The buffer is not large enough to hold the data. The required size is specified by packageFullNameLength. + /// + /// + /// + /// + /// For info about string size limits, see Identity constants. + /// Examples + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-getpackagefullnamefromtoken LONG + // GetPackageFullNameFromToken( HANDLE token, UINT32 *packageFullNameLength, PWSTR packageFullName ); + [DllImport(Lib.KernelBase, SetLastError = false, ExactSpelling = true, CharSet = CharSet.Unicode)] + [PInvokeData("appmodel.h", MSDNShortId = "7B0D574E-A2F5-4D08-AEFB-9E040BBC729F")] + public static extern Win32Error GetPackageFullNameFromToken(HTOKEN token, ref uint packageFullNameLength, [Optional] StringBuilder? packageFullName); + + /// + /// Gets the package information for the specified package. + /// + /// + /// Type: PACKAGE_INFO_REFERENCE + /// A reference to package information. + /// + /// + /// Type: const UINT32 + /// The package constants that specify how package information is retrieved. + /// + /// + /// Type: UINT32* + /// On input, the size of buffer, in bytes. On output, the size of the package information returned, in bytes. + /// + /// + /// Type: BYTE* + /// The package information, represented as an array of PACKAGE_INFO structures. + /// + /// + /// Type: UINT32* + /// The number of packages in the buffer. + /// + /// + /// Type: LONG + /// + /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error + /// codes include the following. + /// + /// + /// + /// Return code + /// Description + /// + /// + /// ERROR_INSUFFICIENT_BUFFER + /// The buffer is not large enough to hold the data. The required size is specified by bufferLength. + /// + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-getpackageinfo LONG GetPackageInfo( + // PACKAGE_INFO_REFERENCE packageInfoReference, const UINT32 flags, UINT32 *bufferLength, BYTE *buffer, UINT32 *count ); + [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true)] + [PInvokeData("appmodel.h", MSDNShortId = "28F45B3B-A61F-44D3-B606-6966AD5866FA")] + public static extern Win32Error GetPackageInfo(PACKAGE_INFO_REFERENCE packageInfoReference, uint flags, ref uint bufferLength, IntPtr buffer, out uint count); + + /// + /// Gets the package information for the specified package, with the option to specify the type of folder path to retrieve for the package. + /// + /// + /// Type: PACKAGE_INFO_REFERENCE + /// A reference to package information. + /// + /// + /// Type: const UINT32 + /// The package constants that specify how package information is retrieved. + /// + /// + /// Type: PackagePathType + /// Indicates the type of folder path to retrieve for the package (the original install folder or the mutable folder). + /// + /// + /// Type: UINT32* + /// On input, the size of buffer, in bytes. On output, the size of the package information returned, in bytes. + /// + /// + /// Type: BYTE* + /// The package information, represented as an array of PACKAGE_INFO structures. + /// + /// + /// Type: UINT32* + /// The number of packages in the buffer. + /// + /// + /// Type: LONG + /// + /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error + /// codes include the following. + /// + /// + /// + /// Return code + /// Description + /// + /// + /// ERROR_INSUFFICIENT_BUFFER + /// The buffer is not large enough to hold the data. The required size is specified by bufferLength. + /// + /// + /// + /// + /// The packagePathType parameter is useful for applications that use the windows.mutablePackageDirectories extension in their + /// package manifest. This extension specifies a folder under the %ProgramFiles%\ModifiableWindowsApps path where the contents of + /// the application's install folder are projected so that users can modify the installation files. This feature is currently + /// available only for certain types of desktop PC games that are published by Microsoft and our partners, and it enables these + /// types of games to support mods. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/appmodel/nf-appmodel-getpackageinfo2 LONG GetPackageInfo2( + // PACKAGE_INFO_REFERENCE packageInfoReference, const UINT32 flags, PackagePathType packagePathType, UINT32 *bufferLength, BYTE + // *buffer, UINT32 *count ); + [DllImport(Lib.KernelBase, SetLastError = false, ExactSpelling = true)] + [PInvokeData("appmodel.h")] + public static extern Win32Error GetPackageInfo2(PACKAGE_INFO_REFERENCE packageInfoReference, uint flags, PackagePathType packagePathType, ref uint bufferLength, IntPtr buffer, out uint count); + + /// + /// Gets the path for the specified package. + /// + /// + /// Type: const PACKAGE_ID* + /// The package identifier. + /// + /// + /// Type: const UINT32 + /// Reserved, do not use. + /// + /// + /// Type: UINT32* + /// + /// On input, the size of the path buffer, in characters. On output, the size of the package path returned, in characters, including + /// the null-terminator. + /// + /// + /// + /// Type: PWSTR + /// The package path. + /// + /// + /// Type: LONG + /// + /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error + /// codes include the following. + /// + /// + /// + /// Return code + /// Description + /// + /// + /// ERROR_INSUFFICIENT_BUFFER + /// The buffer specified by path is not large enough to hold the data. The required size is specified by pathLength. + /// + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-getpackagepath LONG GetPackagePath( const PACKAGE_ID + // *packageId, const UINT32 reserved, UINT32 *pathLength, PWSTR path ); + [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true, CharSet = CharSet.Unicode)] + [PInvokeData("appmodel.h", MSDNShortId = "BDA0DD87-A36D-486B-BF89-EA5CC105C742")] + public static extern Win32Error GetPackagePath(in PACKAGE_ID packageId, uint reserved, ref uint pathLength, [Optional] StringBuilder? path); + + /// + /// Gets the path of the specified package. + /// + /// + /// Type: PCWSTR + /// The full name of the package. + /// + /// + /// Type: UINT32* + /// + /// A pointer to a variable that holds the number of characters ( WCHAR s) in the package path string, which includes the null-terminator. + /// + /// + /// First you pass NULL to path to get the number of characters. You use this number to allocate memory space for path. Then + /// you pass the address of this memory space to fill path. + /// + /// + /// + /// Type: PWSTR + /// A pointer to memory space that receives the package path string, which includes the null-terminator. + /// + /// + /// Type: LONG + /// + /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error + /// codes include the following. + /// + /// + /// + /// Return code + /// Description + /// + /// + /// ERROR_INSUFFICIENT_BUFFER + /// The buffer specified by path is not large enough to hold the data. The required size is specified by pathLength. + /// + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-getpackagepathbyfullname LONG GetPackagePathByFullName( + // PCWSTR packageFullName, UINT32 *pathLength, PWSTR path ); + [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true, CharSet = CharSet.Unicode)] + [PInvokeData("appmodel.h", MSDNShortId = "9C25708C-1464-4C59-9740-E9F105116385")] + public static extern Win32Error GetPackagePathByFullName(string packageFullName, ref uint pathLength, [Optional] StringBuilder? path); + + /// Gets the path of the specified package, with the option to specify the type of folder path to retrieve for the package. + /// + /// Type: PCWSTR + /// The full name of the package. + /// + /// + /// Type: PackagePathType + /// Indicates the type of folder path to retrieve for the package (the original install folder or the mutable folder). + /// + /// + /// Type: UINT32* + /// + /// A pointer to a variable that holds the number of characters ( WCHAR s) in the package path string, which includes the null-terminator. + /// + /// + /// First you pass NULL to path to get the number of characters. You use this number to allocate memory space for path. Then + /// you pass the address of this memory space to fill path. + /// + /// + /// + /// Type: PWSTR + /// A pointer to memory space that receives the package path string, which includes the null-terminator. + /// + /// + /// Type: LONG + /// + /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error + /// codes include the following. + /// + /// + /// + /// Return code + /// Description + /// + /// + /// ERROR_INSUFFICIENT_BUFFER + /// The buffer specified by path is not large enough to hold the data. The required size is specified by pathLength. + /// + /// + /// + /// + /// The packagePathType parameter is useful for applications that use the windows.mutablePackageDirectories extension in their + /// package manifest. This extension specifies a folder under the %ProgramFiles%\ModifiableWindowsApps path where the contents of + /// the application's install folder are projected so that users can modify the installation files. This feature is currently + /// available only for certain types of desktop PC games that are published by Microsoft and our partners, and it enables these + /// types of games to support mods. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/appmodel/nf-appmodel-getpackagepathbyfullname2 LONG GetPackagePathByFullName2( + // PCWSTR packageFullName, PackagePathType packagePathType, UINT32 *pathLength, PWSTR path ); + [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true)] + [PInvokeData("appmodel.h")] + public static extern Win32Error GetPackagePathByFullName2([MarshalAs(UnmanagedType.LPWStr)] string packageFullName, PackagePathType packagePathType, + ref uint pathLength, [Optional, MarshalAs(UnmanagedType.LPWStr)] StringBuilder? path); + + /// Gets the packages with the specified family name for the current user. + /// The package family name. + /// A pointer to the strings of package full names. + /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. + // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-getpackagesbypackagefamily LONG + // GetPackagesByPackageFamily( PCWSTR packageFamilyName, UINT32 *count, PWSTR *packageFullNames, UINT32 *bufferLength, WCHAR *buffer ); + [PInvokeData("appmodel.h", MSDNShortId = "C2163203-D654-4491-9090-0CC43F42EC35")] + public static Win32Error GetPackagesByPackageFamily(string packageFamilyName, out string?[] packageFullNames) + { + uint count = 0, bufferLength = 0; + packageFullNames = new string[0]; + Win32Error err = GetPackagesByPackageFamily(packageFamilyName, ref count, default, ref bufferLength, default); + if (err != Win32Error.ERROR_INSUFFICIENT_BUFFER) + return err; + + using InteropServices.SafeCoTaskMemHandle mem = new(count * IntPtr.Size + bufferLength * StringHelper.GetCharSize(CharSet.Unicode)); + IntPtr buffer = mem.DangerousGetHandle().Offset(count * IntPtr.Size); + err = GetPackagesByPackageFamily(packageFamilyName, ref count, mem, ref bufferLength, buffer); + if (err.Succeeded) + packageFullNames = mem.ToStringEnum((int)count, CharSet.Unicode).ToArray(); + return err; + } + + /// Gets the packages with the specified family name for the current user. + /// + /// Type: PCWSTR + /// The package family name. + /// + /// + /// Type: UINT32* + /// A pointer to a variable that holds the number of package full names. + /// + /// First you pass NULL to packageFullNames to get the number of package full names. You use this number to allocate memory space + /// for packageFullNames. Then you pass the address of this number to fill packageFullNames. + /// + /// + /// + /// Type: PWSTR* + /// A pointer to the strings of package full names. + /// + /// + /// Type: UINT32* + /// A pointer to a variable that holds the number of characters in the string of package full names. + /// + /// First you pass NULL to buffer to get the number of characters. You use this number to allocate memory space for buffer. Then + /// you pass the address of this number to fill buffer. + /// + /// + /// + /// Type: WCHAR* + /// The string of characters for all of the package full names. + /// + /// + /// Type: LONG + /// + /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error codes + /// include the following. + /// + /// + /// + /// Return code + /// Description + /// + /// + /// ERROR_INSUFFICIENT_BUFFER + /// One or more buffer is not large enough to hold the data. The required size is specified by either count or buffer. + /// + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-getpackagesbypackagefamily LONG + // GetPackagesByPackageFamily( PCWSTR packageFamilyName, UINT32 *count, PWSTR *packageFullNames, UINT32 *bufferLength, WCHAR *buffer ); + [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true, CharSet = CharSet.Unicode)] + [PInvokeData("appmodel.h", MSDNShortId = "C2163203-D654-4491-9090-0CC43F42EC35")] + public static extern Win32Error GetPackagesByPackageFamily(string packageFamilyName, ref uint count, + [Out] IntPtr packageFullNames, ref uint bufferLength, [Out] IntPtr buffer); + + /// + /// Gets the origin of the specified package. + /// + /// + /// Type: PCWSTR + /// The full name of the package. + /// + /// + /// Type: PackageOrigin* + /// + /// A pointer to a variable that receives a PackageOrigin-typed value that indicates the origin of the package specified by packageFullName. + /// + /// + /// + /// Type: LONG + /// + /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error + /// codes include the following. + /// + /// + /// + /// Return code + /// Description + /// + /// + /// ERROR_INVALID_PARAMETER + /// The packageFullName parameter isn't valid. + /// + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-getstagedpackageorigin LONG GetStagedPackageOrigin( + // PCWSTR packageFullName, PackageOrigin *origin ); + [DllImport(Lib.KernelBase, SetLastError = false, ExactSpelling = true, CharSet = CharSet.Unicode)] + [PInvokeData("appmodel.h", MSDNShortId = "7A1EE2CA-83CE-4E03-85A5-0061E29EB49B")] + public static extern Win32Error GetStagedPackageOrigin(string packageFullName, out PackageOrigin origin); + + /// + /// Gets the path of the specified staged package. + /// + /// + /// Type: PCWSTR + /// The full name of the staged package. + /// + /// + /// Type: UINT32* + /// + /// A pointer to a variable that holds the number of characters ( WCHAR s) in the package path string, which includes the null-terminator. + /// + /// + /// First you pass NULL to path to get the number of characters. You use this number to allocate memory space for path. Then + /// you pass the address of this memory space to fill path. + /// + /// + /// + /// Type: PWSTR + /// A pointer to memory space that receives the package path string, which includes the null-terminator. + /// + /// + /// Type: LONG + /// + /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error + /// codes include the following. + /// + /// + /// + /// Return code + /// Description + /// + /// + /// ERROR_INSUFFICIENT_BUFFER + /// The buffer specified by path is not large enough to hold the data. The required size is specified by pathLength. + /// + /// + /// + /// + /// + /// This function succeeds if the package is staged, regardless of the user context or if the package is registered for the current user. + /// + /// Examples + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-getstagedpackagepathbyfullname LONG + // GetStagedPackagePathByFullName( PCWSTR packageFullName, UINT32 *pathLength, PWSTR path ); + [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true)] + [PInvokeData("appmodel.h", MSDNShortId = "F0A37D77-6262-44B1-BEC5-083E41BDE139")] + public static extern Win32Error GetStagedPackagePathByFullName([MarshalAs(UnmanagedType.LPWStr)] string packageFullName, ref uint pathLength, + [Optional, MarshalAs(UnmanagedType.LPWStr)] StringBuilder? path); + + /// + /// Gets the path of the specified staged package, with the option to specify the type of folder path to retrieve for the package. + /// + /// + /// Type: PCWSTR + /// The full name of the staged package. + /// + /// + /// Type: PackagePathType + /// Indicates the type of folder path to retrieve for the package (the original install folder or the mutable folder). + /// + /// + /// Type: UINT32* + /// + /// A pointer to a variable that holds the number of characters ( WCHAR s) in the package path string, which includes the null-terminator. + /// + /// + /// First you pass NULL to path to get the number of characters. You use this number to allocate memory space for path. Then + /// you pass the address of this memory space to fill path. + /// + /// + /// + /// Type: PWSTR + /// A pointer to memory space that receives the package path string, which includes the null-terminator. + /// + /// + /// Type: LONG + /// + /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error + /// codes include the following. + /// + /// + /// + /// Return code + /// Description + /// + /// + /// ERROR_INSUFFICIENT_BUFFER + /// The buffer specified by path is not large enough to hold the data. The required size is specified by pathLength. + /// + /// + /// + /// + /// The packagePathType parameter is useful for applications that use the windows.mutablePackageDirectories extension in their + /// package manifest. This extension specifies a folder under the %ProgramFiles%\ModifiableWindowsApps path where the contents of + /// the application's install folder are projected so that users can modify the installation files. This feature is currently + /// available only for certain types of desktop PC games that are published by Microsoft and our partners, and it enables these + /// types of games to support mods. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/appmodel/nf-appmodel-getstagedpackagepathbyfullname2 LONG + // GetStagedPackagePathByFullName2( PCWSTR packageFullName, PackagePathType packagePathType, UINT32 *pathLength, PWSTR path ); + [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true)] + [PInvokeData("appmodel.h")] + public static extern Win32Error GetStagedPackagePathByFullName2([MarshalAs(UnmanagedType.LPWStr)] string packageFullName, PackagePathType packagePathType, + ref uint pathLength, [Optional, MarshalAs(UnmanagedType.LPWStr)] StringBuilder? path); + + /// + /// Opens the package information of the specified package. + /// + /// + /// Type: PCWSTR + /// The full name of the package. + /// + /// + /// Type: const UINT32 + /// Reserved; must be 0. + /// + /// + /// Type: PACKAGE_INFO_REFERENCE* + /// A reference to package information. + /// + /// + /// Type: LONG + /// + /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error + /// codes include the following. + /// + /// + /// + /// Return code + /// Description + /// + /// + /// ERROR_NOT_FOUND + /// The package is not installed for the current user. + /// + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-openpackageinfobyfullname LONG + // OpenPackageInfoByFullName( PCWSTR packageFullName, const UINT32 reserved, PACKAGE_INFO_REFERENCE *packageInfoReference ); + [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true)] + [PInvokeData("appmodel.h", MSDNShortId = "9ECFC757-1CB3-43A1-BA45-9AF72CAB240E")] + public static extern Win32Error OpenPackageInfoByFullName([MarshalAs(UnmanagedType.LPWStr)] string packageFullName, uint reserved, ref PACKAGE_INFO_REFERENCE packageInfoReference); + + /// + /// Gets the package family name for the specified package full name. + /// + /// + /// Type: PCWSTR + /// The full name of a package. + /// + /// + /// Type: UINT32* + /// + /// On input, the size of the packageFamilyName buffer, in characters. On output, the size of the package family name returned, in + /// characters, including the null terminator. + /// + /// + /// + /// Type: PWSTR + /// The package family name. + /// + /// + /// Type: LONG + /// + /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error + /// codes include the following. + /// + /// + /// + /// Return code + /// Description + /// + /// + /// ERROR_INSUFFICIENT_BUFFER + /// The buffer is not large enough to hold the data. The required size is specified by packageFamilyNameLength. + /// + /// + /// + /// + /// For info about string size limits, see Identity constants. + /// Examples + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-packagefamilynamefromfullname LONG + // PackageFamilyNameFromFullName( PCWSTR packageFullName, UINT32 *packageFamilyNameLength, PWSTR packageFamilyName ); + [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true, CharSet = CharSet.Unicode)] + [PInvokeData("appmodel.h", MSDNShortId = "98E95CE5-E970-4A19-BAD3-994DAEC4BEA0")] + public static extern Win32Error PackageFamilyNameFromFullName(string packageFullName, ref uint packageFamilyNameLength, + [Optional] StringBuilder? packageFamilyName); + + /// + /// Gets the package family name for the specified package identifier. + /// + /// + /// Type: const PACKAGE_ID* + /// The package identifier. + /// + /// + /// Type: UINT32* + /// + /// On input, the size of the packageFamilyName buffer, in characters. On output, the size of the package family name returned, in + /// characters, including the null terminator. + /// + /// + /// + /// Type: PWSTR + /// The package family name. + /// + /// + /// Type: LONG + /// + /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error + /// codes include the following. + /// + /// + /// + /// Return code + /// Description + /// + /// + /// ERROR_INSUFFICIENT_BUFFER + /// The buffer is not large enough to hold the data. The required size is specified by packageFamilyNameLength. + /// + /// + /// + /// + /// For info about string size limits, see Identity constants. + /// Examples + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-packagefamilynamefromid LONG PackageFamilyNameFromId( + // const PACKAGE_ID *packageId, UINT32 *packageFamilyNameLength, PWSTR packageFamilyName ); + [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true)] + [PInvokeData("appmodel.h", MSDNShortId = "198DAB6B-21D2-4ACB-87DF-B3F4EFBEE323")] + public static extern Win32Error PackageFamilyNameFromId(in PACKAGE_ID packageId, ref uint packageFamilyNameLength, + [Optional, MarshalAs(UnmanagedType.LPWStr)] StringBuilder? packageFamilyName); + + /// + /// Gets the package full name for the specified package identifier (ID). + /// + /// + /// Type: const PACKAGE_ID* + /// The package ID. + /// + /// + /// Type: UINT32* + /// + /// On input, the size of the packageFullName buffer, in characters. On output, the size of the package full name returned, in + /// characters, including the null terminator. + /// + /// + /// + /// Type: PWSTR + /// The package full name. + /// + /// + /// Type: LONG + /// + /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error + /// codes include the following. + /// + /// + /// + /// Return code + /// Description + /// + /// + /// ERROR_INSUFFICIENT_BUFFER + /// The buffer is not large enough to hold the data. The required size is specified by packageFullNameLength. + /// + /// + /// + /// + /// For info about string size limits, see Identity constants. + /// Examples + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-packagefullnamefromid LONG PackageFullNameFromId( const + // PACKAGE_ID *packageId, UINT32 *packageFullNameLength, PWSTR packageFullName ); + [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true)] + [PInvokeData("appmodel.h", MSDNShortId = "0024AF55-295E-49B1-90C2-9144D336529B")] + public static extern Win32Error PackageFullNameFromId(in PACKAGE_ID packageId, ref uint packageFullNameLength, + [Optional, MarshalAs(UnmanagedType.LPWStr)] StringBuilder? packageFullName); + + /// + /// Gets the package identifier (ID) for the specified package full name. + /// + /// + /// Type: PCWSTR + /// The full name of a package. + /// + /// + /// Type: const UINT32 + /// The package constants that specify how package information is retrieved. The PACKAGE_INFORMATION_* flags are supported. + /// + /// + /// Type: UINT32* + /// On input, the size of buffer, in bytes. On output, the size of the data returned, in bytes. + /// + /// + /// Type: BYTE* + /// The package ID, represented as a PACKAGE_ID structure. + /// + /// + /// Type: LONG + /// + /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error + /// codes include the following. + /// + /// + /// + /// Return code + /// Description + /// + /// + /// ERROR_INSUFFICIENT_BUFFER + /// The buffer is not large enough to hold the data. The required size is specified by bufferLength. + /// + /// + /// ERROR_NOT_FOUND + /// The package is not installed for the user. + /// + /// + /// + /// + /// If flags specifies PACKAGE_INFORMATION_BASIC, the following fields are retrieved: + /// + /// + /// name + /// + /// + /// processorArchitecture + /// + /// + /// publisherId + /// + /// + /// resourceId + /// + /// + /// version + /// + /// + /// If flags specifies PACKAGE_INFORMATION_FULL, the following fields are retrieved: + /// + /// + /// name + /// + /// + /// processorArchitecture + /// + /// + /// publisher + /// + /// + /// publisherId + /// + /// + /// resourceId + /// + /// + /// version + /// + /// + /// + /// A request for PACKAGE_INFORMATION_FULL succeeds only if the package corresponding to packageFullName is installed for and + /// accessible to the current user. If the package full name is syntactically correct but does not correspond to a package that is + /// installed for and accessible to the current user, the function returns ERROR_NOT_FOUND. + /// + /// For info about string size limits, see Identity constants. + /// Examples + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-packageidfromfullname LONG PackageIdFromFullName( + // PCWSTR packageFullName, const UINT32 flags, UINT32 *bufferLength, BYTE *buffer ); + [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true)] + [PInvokeData("appmodel.h", MSDNShortId = "EED832F8-E4F7-4A0F-93E2-451F78F67767")] + public static extern Win32Error PackageIdFromFullName([MarshalAs(UnmanagedType.LPWStr)] string packageFullName, PACKAGE_FLAGS flags, ref uint bufferLength, IntPtr buffer); + + /// + /// Gets the package name and publisher identifier (ID) for the specified package family name. + /// + /// + /// Type: PCWSTR + /// The family name of a package. + /// + /// + /// Type: UINT32* + /// + /// On input, the size of the packageName buffer, in characters. On output, the size of the package name returned, in characters, + /// including the null-terminator. + /// + /// + /// + /// Type: PWSTR + /// The package name. + /// + /// + /// Type: UINT32* + /// + /// On input, the size of the packagePublishId buffer, in characters. On output, the size of the publisher ID returned, in + /// characters, including the null-terminator. + /// + /// + /// + /// Type: PWSTR + /// The package publisher ID. + /// + /// + /// Type: LONG + /// + /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error + /// codes include the following. + /// + /// + /// + /// Return code + /// Description + /// + /// + /// ERROR_INSUFFICIENT_BUFFER + /// One of the buffers is not large enough to hold the data. The required sizes are specified by packageNameLength and packagePublisherIdLength. + /// + /// + /// + /// + /// For info about string size limits, see Identity constants. + /// Examples + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-packagenameandpublisheridfromfamilyname LONG + // PackageNameAndPublisherIdFromFamilyName( PCWSTR packageFamilyName, UINT32 *packageNameLength, PWSTR packageName, UINT32 + // *packagePublisherIdLength, PWSTR packagePublisherId ); + [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true, CharSet = CharSet.Unicode)] + [PInvokeData("appmodel.h", MSDNShortId = "4AA5BD75-F865-40D6-9C10-E54C197D47C4")] + public static extern Win32Error PackageNameAndPublisherIdFromFamilyName(string packageFamilyName, ref uint packageNameLength, + [Optional] StringBuilder? packageName, ref uint packagePublisherIdLength, [Optional] StringBuilder? packagePublisherId); + + /// + /// Deconstructs an application user model ID to its package family name and package relative application ID (PRAID). + /// + /// + /// Type: PCWSTR + /// The app user model ID. + /// + /// + /// Type: UINT32* + /// + /// A pointer to a variable that holds the number of characters ( WCHAR s) in the package family name string, which includes + /// the null-terminator. + /// + /// + /// First you pass NULL to packageFamilyName to get the number of characters. You use this number to allocate memory space + /// for packageFamilyName. Then you pass the address of this memory space to fill packageFamilyName. + /// + /// + /// + /// Type: PWSTR + /// A pointer to memory space that receives the package family name string, which includes the null-terminator. + /// + /// + /// Type: UINT32* + /// + /// A pointer to a variable that holds the number of characters ( WCHAR s) in the package-relative app ID string, which + /// includes the null-terminator. + /// + /// + /// First you pass NULL to packageRelativeApplicationId to get the number of characters. You use this number to allocate + /// memory space for packageRelativeApplicationId. Then you pass the address of this memory space to fill packageRelativeApplicationId. + /// + /// + /// + /// Type: PWSTR + /// A pointer to memory space that receives the package-relative app ID (PRAID) string, which includes the null-terminator. + /// + /// + /// Type: LONG + /// + /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error + /// codes include the following. + /// + /// + /// + /// Return code + /// Description + /// + /// + /// ERROR_INVALID_PARAMETER + /// The applicationUserModelId parameter isn't valid. + /// + /// + /// ERROR_INSUFFICIENT_BUFFER + /// + /// The buffer specified by packageFamilyName or packageRelativeApplicationId is not large enough to hold the data; the required + /// buffer size, in WCHARs, is stored in the variable pointed to by packageFamilyNameLength or packageRelativeApplicationIdLength. + /// + /// + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-parseapplicationusermodelid LONG + // ParseApplicationUserModelId( PCWSTR applicationUserModelId, UINT32 *packageFamilyNameLength, PWSTR packageFamilyName, UINT32 + // *packageRelativeApplicationIdLength, PWSTR packageRelativeApplicationId ); + [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true, CharSet = CharSet.Unicode)] + [PInvokeData("appmodel.h", MSDNShortId = "03B29E82-611F-47D1-8CB6-047B9BEB4D9E")] + public static extern Win32Error ParseApplicationUserModelId(string applicationUserModelId, ref uint packageFamilyNameLength, + [Optional] StringBuilder? packageFamilyName, ref uint packageRelativeApplicationIdLength, [Optional] StringBuilder? packageRelativeApplicationId); + + /// + /// Removes a resolved package dependency from the current process' package graph (that is, a run-time reference for a framework + /// package dependency that was added by using the AddPackageDependency method). + /// + /// + /// Type: PACKAGEDEPENDENCY_CONTEXT + /// The handle of the package dependency to remove. + /// + /// + /// Type: HRESULT + /// + /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error + /// codes include the following. + /// + /// + /// + /// Return code + /// Description + /// + /// + /// E_INVALIDARG + /// The packageDependencyContext parameter is NULL on input. + /// + /// + /// + /// + /// This function does not unload loaded resources such as DLLs. After removing a package dependency, any files loaded from the + /// package can continue to be used. Future file resolution will fail to see the removed package dependency. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/appmodel/nf-appmodel-removepackagedependency HRESULT RemovePackageDependency( + // PACKAGEDEPENDENCY_CONTEXT packageDependencyContext ); + [DllImport(Lib.KernelBase, SetLastError = false, ExactSpelling = true)] + [PInvokeData("appmodel.h", MSDNShortId = "NF:appmodel.RemovePackageDependency")] + public static extern HRESULT RemovePackageDependency([In] PACKAGEDEPENDENCY_CONTEXT packageDependencyContext); + + /// Creates an install-time reference for a framework package dependency for the current app, using the specified package family name, minimum version, and additional criteria. + /// + /// Type: PSID + /// The user scope of the package dependency. If NULL, the caller's user context is used. Must be NULL if CreatePackageDependencyOptions_ScopeIsSystem is specified. + /// + /// + /// Type: PCWSTR + /// The package family name of the framework package on which to take dependency. + /// + /// + /// Type: PACKAGE_VERSION + /// The minimum version of the framework package on which to take dependency. + /// + /// + /// Type: PackageDependencyProcessorArchitectures + /// The processor architectures of the package dependency. + /// + /// + /// Type: PackageDependencyLifetimeKind + /// The type of artifact to use to define the lifetime of the package dependency. For more information, see the remarks. + /// + /// + /// Type: PCWSTR + /// The name of the artifact used to define the lifetime of the package dependency. Must be NULL if the lifetimeKind parameter is PackageDependencyLifetimeKind_Process. For more information, see the remarks. + /// + /// + /// Type: CreatePackageDependencyOptions + /// The options to apply when creating the package dependency. + /// + /// + /// Type: PWSTR* + /// The ID of the new package dependency. Use the HeapAlloc function to allocate memory for this parameter, and use HeapFree to deallocate the memory. + /// + /// + /// Type: HRESULT + /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error codes include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// E_INVALIDARG + /// The packageDependencyId parameter is NULL on input. + /// + /// + /// + /// + /// In your app's installer or during the first run of your app, call this method to specify a set of criteria for a framework package you want to use in your app. This informs the OS that your app has a dependency upon a framework package that meets the specified criteria. If one or more framework packages are installed that meet the criteria, Windows will ensure that at least one of these framework packages will remain installed until the install-time reference is deleted. For more information, see Use the dynamic dependency API to reference framework packages at run time. + /// This function fails if the specified dependency criteria cannot be resolved to a specific package. This package resolution check is skipped if CreatePackageDependencyOptions_DoNotVerifyDependencyResolution is specified for the options parameter. This is useful for installers running as user contexts other than the target user (for example, installers running as LocalSystem). + /// + // https://docs.microsoft.com/en-us/windows/win32/api/appmodel/nf-appmodel-trycreatepackagedependency + // HRESULT TryCreatePackageDependency( PSID user, PCWSTR packageFamilyName, PACKAGE_VERSION minVersion, PackageDependencyProcessorArchitectures packageDependencyProcessorArchitectures, PackageDependencyLifetimeKind lifetimeKind, PCWSTR lifetimeArtifact, CreatePackageDependencyOptions options, PWSTR *packageDependencyId ); + [DllImport(Lib.KernelBase, SetLastError = false, ExactSpelling = true)] + [PInvokeData("appmodel.h", MSDNShortId = "NF:appmodel.TryCreatePackageDependency")] + public static extern HRESULT TryCreatePackageDependency([In, Optional] PSID user, [MarshalAs(UnmanagedType.LPWStr)] string packageFamilyName, + PACKAGE_VERSION minVersion, PackageDependencyProcessorArchitectures packageDependencyProcessorArchitectures, + PackageDependencyLifetimeKind lifetimeKind, [MarshalAs(UnmanagedType.LPWStr)] string lifetimeArtifact, + CreatePackageDependencyOptions options, out SafeHeapBlock packageDependencyId); + + /// + /// Represents package identification information, such as name, version, and publisher. + /// + /// + /// For info about string size limits, see Identity constants. + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/ns-appmodel-package_id typedef struct PACKAGE_ID { UINT32 reserved; + // UINT32 processorArchitecture; PACKAGE_VERSION version; PWSTR name; PWSTR publisher; PWSTR resourceId; PWSTR publisherId; }; + [PInvokeData("appmodel.h", MSDNShortId = "4B15281A-2227-47B7-A750-0A01DB8543FC")] + [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)] + public struct PACKAGE_ID + { + /// + /// Type: UINT32 + /// Reserved; do not use. + /// + public uint reserved; /// - /// The AppPolicyThreadInitializationType enumeration indicates the kind of initialization that should be automatically performed - /// for a process when beginthread[ex] creates a thread. - /// - // typedef enum AppPolicyThreadInitializationType { AppPolicyThreadInitializationType_None = 0, - // AppPolicyThreadInitializationType_InitializeWinRT = 1} AppPolicyThreadInitializationType; https://msdn.microsoft.com/en-us/library/windows/desktop/mt829661(v=vs.85).aspx - [PInvokeData("AppModel.h", MSDNShortId = "mt829661")] - public enum AppPolicyThreadInitializationType - { - /// Indicates that no initialization should be performed. - AppPolicyThreadInitializationType_None, - - /// Indicates that Windows Runtime initialization should be performed. - AppPolicyThreadInitializationType_InitializeWinRT, - } - - /// - /// Specifies the processor architectures supported by a package. - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/appxpackaging/ne-appxpackaging-appx_package_architecture typedef enum - // APPX_PACKAGE_ARCHITECTURE { APPX_PACKAGE_ARCHITECTURE_X86 , APPX_PACKAGE_ARCHITECTURE_ARM , APPX_PACKAGE_ARCHITECTURE_X64 , - // APPX_PACKAGE_ARCHITECTURE_NEUTRAL , APPX_PACKAGE_ARCHITECTURE_ARM64 } ; - [PInvokeData("appxpackaging.h", MSDNShortId = "8BC7ABF0-448F-4405-AA82-49C6DB3F230C")] - public enum APPX_PACKAGE_ARCHITECTURE - { - /// The x86 processor architecture. - APPX_PACKAGE_ARCHITECTURE_X86 = 0, - - /// The ARM processor architecture. - APPX_PACKAGE_ARCHITECTURE_ARM = 5, - - /// The x64 processor architecture. - APPX_PACKAGE_ARCHITECTURE_X64 = 9, - - /// Any processor architecture. - APPX_PACKAGE_ARCHITECTURE_NEUTRAL = 11, - - /// The 64-bit ARM processor architecture. - APPX_PACKAGE_ARCHITECTURE_ARM64 = 12, - } - - /// Defines options that can be applied when creating a package dependency by using the TryCreatePackageDependency function. - // https://docs.microsoft.com/en-us/windows/win32/api/appmodel/ne-appmodel-createpackagedependencyoptions typedef enum - // CreatePackageDependencyOptions { CreatePackageDependencyOptions_None, - // CreatePackageDependencyOptions_DoNotVerifyDependencyResolution, CreatePackageDependencyOptions_ScopeIsSystem } ; - [PInvokeData("appmodel.h", MSDNShortId = "NE:appmodel.CreatePackageDependencyOptions")] - [Flags] - public enum CreatePackageDependencyOptions - { - /// No options are applied. - CreatePackageDependencyOptions_None = 0, - - /// - /// Disables dependency resolution when pinning a package dependency. This is useful for installers running as user contexts - /// other than the target user (for example, installers running as LocalSystem). - /// - CreatePackageDependencyOptions_DoNotVerifyDependencyResolution = 1, - - /// - /// Defines the package dependency for the system, accessible to all users (by default, the package dependency is defined for a - /// specific user). This option requires the caller has administrative privileges. - /// - CreatePackageDependencyOptions_ScopeIsSystem = 2, - } - - /// Specifies how packages are to be processed. - // https://docs.microsoft.com/en-us/windows/desktop/appxpkg/package-constants - [PInvokeData("", MSDNShortId = "72E565C3-6CFD-47E3-8BAC-17D6E86B99DA")] - [Flags] - public enum PACKAGE_FLAGS : uint - { - /// The maximum number of apps in a package. - PACKAGE_APPLICATIONS_MAX_COUNT = 100, - - /// The minimum number of apps in a package. - PACKAGE_APPLICATIONS_MIN_COUNT = 0, - - /// The maximum number of resource packages a package can have. - PACKAGE_FAMILY_MAX_RESOURCE_PACKAGES = 512, - - /// The minimum number of resource packages a package can have. - PACKAGE_FAMILY_MIN_RESOURCE_PACKAGES = 0, - - /// - /// Process all packages in the dependency graph. This is equivalent to PACKAGE_FILTER_HEAD | PACKAGE_FILTER_DIRECT. Note: - /// PACKAGE_FILTER_ALL_LOADED may be altered or unavailable for releases after Windows 8.1. Instead, use PACKAGE_FILTER_HEAD | PACKAGE_FILTER_DIRECT. - /// - PACKAGE_FILTER_ALL_LOADED = 0x00000000, - - /// Process bundle packages in the package graph. - PACKAGE_FILTER_BUNDLE = 0x00000080, - - /// Process the directly dependent packages of the head (first) package in the dependency graph. - PACKAGE_FILTER_DIRECT = 0x00000020, - - /// Process the first package in the dependency graph. - PACKAGE_FILTER_HEAD = 0x00000010, - - /// Process bundle packages in the package graph. - PACKAGE_FILTER_OPTIONAL = 0x00020000, - - /// Process resource packages in the package graph. - PACKAGE_FILTER_RESOURCE = 0x00000040, - - /// The maximum size of a package graph. - PACKAGE_GRAPH_MAX_SIZE = (1 + PACKAGE_MAX_DEPENDENCIES + PACKAGE_FAMILY_MAX_RESOURCE_PACKAGES), - - /// The minimum size of a package graph. - PACKAGE_GRAPH_MIN_SIZE = 1, - - /// Retrieve basic information. - PACKAGE_INFORMATION_BASIC = 0x00000000, - - /// Retrieve full information. - PACKAGE_INFORMATION_FULL = 0x00000100, - - /// The maximum number of packages a package depends on. - PACKAGE_MAX_DEPENDENCIES = 128, - - /// The minimum number of packages a package depends on. - PACKAGE_MIN_DEPENDENCIES = 0, - - /// The package is a bundle package. - PACKAGE_PROPERTY_BUNDLE = 0x00000004, - - /// The package was registered with the DeploymentOptions enumeration. - PACKAGE_PROPERTY_DEVELOPMENT_MODE = 0x00010000, - - /// The package is a framework. - PACKAGE_PROPERTY_FRAMEWORK = 0x00000001, - - /// The package is an optional package. - PACKAGE_PROPERTY_OPTIONAL = 0x00000008, - - /// The package is a resource package. - PACKAGE_PROPERTY_RESOURCE = 0x00000002, - } - - /// Specifies values that indicate the type of artifact that is used to define the lifetime of a package dependency. - // https://docs.microsoft.com/en-us/windows/win32/api/appmodel/ne-appmodel-packagedependencylifetimekind typedef enum - // PackageDependencyLifetimeKind { PackageDependencyLifetimeKind_Process, PackageDependencyLifetimeKind_FilePath, - // PackageDependencyLifetimeKind_RegistryKey } ; - [PInvokeData("appmodel.h", MSDNShortId = "NE:appmodel.PackageDependencyLifetimeKind")] - public enum PackageDependencyLifetimeKind - { - /// - /// The current process is the lifetime artifact. The package dependency is implicitly deleted when the process terminates. - /// - PackageDependencyLifetimeKind_Process, - - /// - /// The lifetime artifact is an absolute filename or path. The package dependency is implicitly deleted when this is deleted. - /// - PackageDependencyLifetimeKind_FilePath, - - /// - /// The lifetime artifact is a registry key in the format - /// root - /// \ - /// subkey - /// , where - /// root - /// - /// is one of the following: HKEY_LOCAL_MACHINE, HKEY_CURRENT_USER, HKEY_CLASSES_ROOT, or HKEY_USERS. The package dependency is - /// implicitly deleted when this is deleted. - /// - /// - PackageDependencyLifetimeKind_RegistryKey, - } - - /// - /// Defines the processor architectures for a framework package dependency that you create by using the TryCreatePackageDependency function. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/appmodel/ne-appmodel-packagedependencyprocessorarchitectures typedef enum - // PackageDependencyProcessorArchitectures { PackageDependencyProcessorArchitectures_None, - // PackageDependencyProcessorArchitectures_Neutral, PackageDependencyProcessorArchitectures_X86, - // PackageDependencyProcessorArchitectures_X64, PackageDependencyProcessorArchitectures_Arm, - // PackageDependencyProcessorArchitectures_Arm64, PackageDependencyProcessorArchitectures_X86A64 } ; - [PInvokeData("appmodel.h", MSDNShortId = "NE:appmodel.PackageDependencyProcessorArchitectures")] - [Flags] - public enum PackageDependencyProcessorArchitectures - { - /// No processor architecture is specified. - PackageDependencyProcessorArchitectures_None = 0x0000, - - /// Specifies the neutral architecture. - PackageDependencyProcessorArchitectures_Neutral = 0x0001, - - /// Specifies the x86 architecture. - PackageDependencyProcessorArchitectures_X86 = 0x0002, - - /// Specifies the x64 architecture. - PackageDependencyProcessorArchitectures_X64 = 0x0004, - - /// Specifies the ARM architecture. - PackageDependencyProcessorArchitectures_Arm = 0x0008, - - /// Specifies the ARM64 architecture. - PackageDependencyProcessorArchitectures_Arm64 = 0x0010, - - /// Specifies the x86/A64 architecture. - PackageDependencyProcessorArchitectures_X86A64 = 0x0020, - } - - /// - /// Specifies the origin of a package. - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/ne-appmodel-packageorigin typedef enum PackageOrigin { - // PackageOrigin_Unknown , PackageOrigin_Unsigned , PackageOrigin_Inbox , PackageOrigin_Store , PackageOrigin_DeveloperUnsigned , - // PackageOrigin_DeveloperSigned , PackageOrigin_LineOfBusiness } ; - [PInvokeData("appmodel.h", MSDNShortId = "0CB9CE97-8A54-4BE7-B054-00F29D36CAB2")] - public enum PackageOrigin - { - /// The package's origin is unknown. - PackageOrigin_Unknown, - - /// The package originated as unsigned. - PackageOrigin_Unsigned, - - /// The package was included inbox. - PackageOrigin_Inbox, - - /// The package originated from the Windows Store. - PackageOrigin_Store, - - /// The package originated as developer unsigned. - PackageOrigin_DeveloperUnsigned, - - /// The package originated as developer signed. - PackageOrigin_DeveloperSigned, - - /// The package originated as a line-of-business app. - PackageOrigin_LineOfBusiness, - } - - /// Indicates the type of folder path to retrieve in a query for the path or other info about a package. - /// - /// An application has a mutable install folder if it uses the windows.mutablePackageDirectories extension in its package manifest. - /// This extension specifies a folder under the %ProgramFiles%\ModifiableWindowsApps path where the contents of the application's - /// install folder are projected so that users can modify the installation files. This feature is currently available only for - /// certain types of desktop PC games that are published by Microsoft and our partners, and it enables these types of games to - /// support mods. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/appmodel/ne-appmodel-packagepathtype typedef enum PackagePathType { - // PackagePathType_Install, PackagePathType_Mutable, PackagePathType_Effective } ; - [PInvokeData("appmodel.h")] - public enum PackagePathType - { - /// Retrieve the package path in the original install folder for the application. - PackagePathType_Install, - - /// - /// Retrieve the package path in the mutable install folder for the application, if the application is declared as mutable in - /// the package manifest. - /// - PackagePathType_Mutable, - - /// - /// Retrieve the package path in the mutable folder if the application is declared as mutable in the package manifest, or in the - /// original install folder if the application is not mutable. - /// - PackagePathType_Effective - } - - /// - /// Adds a run-time reference for the framework package dependency you created earlier by using the TryCreatePackageDependency - /// method, with the specified options. After this method successfully returns, your app can activate types and use content from the - /// framework package. - /// - /// - /// Type: PCWSTR - /// - /// The ID of the package dependency to be resolved and added to the invoking process' package graph. This parameter must match a - /// package dependency defined by using the TryCreatePackageDependency function for the calling user or the system (via the - /// CreatePackageDependencyOptions_ScopeIsSystem option), or else an error is returned. - /// - /// - /// - /// Type: INT32 - /// The rank to use to add the resolved package to the caller's package graph. For more information, see the remarks. - /// - /// - /// Type: AddPackageDependencyOptions - /// The options to apply when adding the package dependency. - /// - /// - /// Type: PACKAGEDEPENDENCY_CONTEXT* - /// The handle of the added package dependency. This handle is valid until it is passed to RemovePackageDependency. - /// - /// - /// Type: PCWSTR* - /// - /// The full name of the package to which the dependency has been resolved. Use the HeapAlloc function to allocate memory for this - /// parameter, and use HeapFree to deallocate the memory. - /// - /// - /// - /// Type: HRESULT - /// - /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error - /// codes include the following. - /// - /// - /// - /// Return code - /// Description - /// - /// - /// E_INVALIDARG - /// The packageDependencyId or packageDependencyContext parameter is NULL on input. - /// - /// - /// - /// - /// - /// Calling this method resolves the framework package dependency to a specific package on the system. It also informs the OS that - /// the framework package is in active use and to handle any version updates in a side-by-side manner (effectively delay - /// uninstalling or otherwise servicing the older version until after your app is done using it). Package resolution is specific to - /// a user and can return different values for different users on a system. - /// - /// - /// Each successful AddPackageDependency call adds the resolved package to the calling process' package graph, even if - /// already present. There is no duplicate detection or filtering applied by the API (that is, multiple references from a package is - /// not harmful). After resolution is complete, the package dependency stays resolved for that user until the last reference across - /// all processes for that user is removed via RemovePackageDependency or the process is terminated. - /// - /// - /// After this method successfully returns, your app can activate types and use content from the framework package until - /// RemovePackageDependency is called. - /// - /// - /// If multiple packages are present in the package graph with the same rank as the call to AddPackageDependency, the - /// resolved package is (by default) added after others of the same rank. To add a package before others of the same rank, specify - /// AddPackageDependencyOptions_PrependIfRankCollision for the options parameter. - /// - /// For more information, see Use the dynamic dependency API to reference framework packages at run time. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/appmodel/nf-appmodel-addpackagedependency HRESULT AddPackageDependency( PCWSTR - // packageDependencyId, INT32 rank, AddPackageDependencyOptions options, PACKAGEDEPENDENCY_CONTEXT *packageDependencyContext, PWSTR - // *packageFullName ); - [DllImport(Lib.KernelBase, SetLastError = false, ExactSpelling = true)] - [PInvokeData("appmodel.h", MSDNShortId = "NF:appmodel.AddPackageDependency")] - public static extern HRESULT AddPackageDependency([MarshalAs(UnmanagedType.LPWStr)] string packageDependencyId, int rank, - AddPackageDependencyOptions options, out PACKAGEDEPENDENCY_CONTEXT packageDependencyContext, out SafeHeapBlock packageFullName); - - /// - /// Retrieves a value indicating whether a process has full or restricted access to the IO devices (file, file stream, directory, - /// physical disk, volume, console buffer, tape drive, communications resource, mailslot, and pipe). - /// - /// A handle that identifies the access token for a process. - /// - /// A pointer to a variable of the AppPolicyCreateFileAccess enumerated type. When the function returns successfully, the - /// variable contains an enumerated constant value indicating whether the process has full or restricted access to the IO devices. - /// - /// - /// If the function succeeds, the function returns ERROR_SUCCESS. - /// - /// If no known create file access policy was found for the process token, the function raises a STATUS_ASSERTION_FAILURE exception - /// and returns ERROR_NOT_FOUND. - /// - /// If either processToken or policy are null, the function returns ERROR_INVALID_PARAMETER. - /// - // LONG WINAPI AppPolicyGetCreateFileAccess( _In_ HANDLE processToken, _Out_ AppPolicyCreateFileAccess *policy); https://msdn.microsoft.com/en-us/library/windows/desktop/mt829655(v=vs.85).aspx - [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true)] - [PInvokeData("AppModel.h", MSDNShortId = "mt829655")] - public static extern Win32Error AppPolicyGetCreateFileAccess(HTOKEN processToken, out AppPolicyCreateFileAccess policy); - - /// Retrieves the method used to end a process. - /// A handle that identifies the access token for a process. - /// - /// A pointer to a variable of the AppPolicyProcessTerminationMethod enumerated type. When the function returns successfully, - /// the variable contains a value indicating the method used to end the process. - /// - /// - /// If the function succeeds, the function returns ERROR_SUCCESS. - /// - /// If no known create file access policy was found for the process token, the function raises a STATUS_ASSERTION_FAILURE exception - /// and returns ERROR_NOT_FOUND. - /// - /// If either processToken or policy are null, the function returns ERROR_INVALID_PARAMETER. - /// - // LONG WINAPI AppPolicyGetProcessTerminationMethod( _In_ HANDLE processToken, _Out_ AppPolicyProcessTerminationMethod *policy); https://msdn.microsoft.com/en-us/library/windows/desktop/mt829656(v=vs.85).aspx - [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true)] - [PInvokeData("AppModel.h", MSDNShortId = "mt829656")] - public static extern Win32Error AppPolicyGetProcessTerminationMethod(HTOKEN processToken, out AppPolicyProcessTerminationMethod policy); - - /// Retrieves the method used for a process to surface developer information, such as asserts, to the user. - /// A handle that identifies the access token for a process. - /// - /// A pointer to a variable of the AppPolicyShowDeveloperDiagnostic enumerated type. When the function returns successfully, - /// the variable contains a value indicating the method used for the process to surface developer information, such as asserts, to - /// the user. - /// - /// - /// If the function succeeds, the function returns ERROR_SUCCESS. - /// - /// If no known create file access policy was found for the process token, the function raises a STATUS_ASSERTION_FAILURE exception - /// and returns ERROR_NOT_FOUND. - /// - /// If either processToken or policy are null, the function returns ERROR_INVALID_PARAMETER. - /// - // LONG WINAPI AppPolicyGetShowDeveloperDiagnostic( _In_ HANDLE processToken, _Out_ AppPolicyShowDeveloperDiagnostic *policy); https://msdn.microsoft.com/en-us/library/windows/desktop/mt829657(v=vs.85).aspx - [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true)] - [PInvokeData("AppModel.h", MSDNShortId = "mt829657")] - public static extern Win32Error AppPolicyGetShowDeveloperDiagnostic(HTOKEN processToken, out AppPolicyShowDeveloperDiagnostic policy); - - /// - /// Retrieves the kind of initialization that should be automatically performed for a process when beginthread[ex] creates a thread. - /// - /// A handle that identifies the access token for a process. - /// - /// A pointer to a variable of the AppPolicyThreadInitializationType enumerated type. When the function returns successfully, - /// the variable contains a value indicating the kind of initialization that should be automatically performed for the process when - /// beginthread[ex] creates a thread. - /// - /// - /// If the function succeeds, the function returns ERROR_SUCCESS. - /// - /// If no known create file access policy was found for the process token, the function raises a STATUS_ASSERTION_FAILURE exception - /// and returns ERROR_NOT_FOUND. - /// - /// If either processToken or policy are null, the function returns ERROR_INVALID_PARAMETER. - /// - // LONG WINAPI AppPolicyGetThreadInitializationType( _In_ HANDLE processToken, _Out_ AppPolicyThreadInitializationType *policy); https://msdn.microsoft.com/en-us/library/windows/desktop/mt829658(v=vs.85).aspx - [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true)] - [PInvokeData("AppModel.h", MSDNShortId = "mt829658")] - public static extern Win32Error AppPolicyGetThreadInitializationType(HTOKEN processToken, out AppPolicyThreadInitializationType policy); - - /// - /// Closes a reference to the specified package information. - /// - /// - /// Type: PACKAGE_INFO_REFERENCE - /// A reference to package information. - /// - /// - /// Type: LONG - /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-closepackageinfo LONG ClosePackageInfo( - // PACKAGE_INFO_REFERENCE packageInfoReference ); - [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true)] - [PInvokeData("appmodel.h", MSDNShortId = "BA84FB47-F241-4120-9441-7E1149F68738")] - public static extern Win32Error ClosePackageInfo(PACKAGE_INFO_REFERENCE packageInfoReference); - - /// - /// Deletes the install-time reference for the framework package dependency you created earlier by using the - /// TryCreatePackageDependency method. This method informs the OS that it is safe to remove the framework package if no other apps - /// have a dependency on it. - /// - /// - /// Type: PCWSTR - /// The ID of the package dependency to remove. - /// - /// - /// - /// - /// Return code - /// Description - /// - /// - /// E_INVALIDARG - /// The packageDependencyId parameter is NULL on input. - /// - /// - /// - /// - /// - /// Removing a package dependency is typically done when an app is uninstalled. A package dependency is implicitly removed if its - /// lifetime artifact (specified via the lifetimeArtifact parameter of the TryCreatePackageDependency function) is deleted. Package - /// dependencies that are not referenced by other packages are elegible to be removed. - /// - /// The caller of this function must have administrative privileges if the package dependency was created using CreatePackageDependencyOptions_ScopeIsSystem. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/appmodel/nf-appmodel-deletepackagedependency - // HRESULT DeletePackageDependency( PCWSTR packageDependencyId ); - [DllImport(Lib.KernelBase, SetLastError = false, ExactSpelling = true)] - [PInvokeData("appmodel.h", MSDNShortId = "NF:appmodel.DeletePackageDependency")] - public static extern HRESULT DeletePackageDependency([MarshalAs(UnmanagedType.LPWStr)] string packageDependencyId); - - /// - /// Finds the packages with the specified family name for the current user. - /// - /// - /// Type: PCWSTR - /// The package family name. - /// - /// /// Type: UINT32 /// - /// The package constants that specify how package information is retrieved. All package constants except - /// PACKAGE_FILTER_ALL_LOADED are supported. + /// The processor architecture of the package. This member must be one of the values of the APPX_PACKAGE_ARCHITECTURE enumeration. /// - /// - /// - /// Type: UINT32* - /// A pointer to a variable that holds the number of package full names that were found. - /// - /// First you pass NULL to packageFullNames to get the number of package full names that were found. You use this number to - /// allocate memory space for packageFullNames. Then you pass the address of this memory space to fill packageFullNames. - /// - /// - /// - /// Type: PWSTR* - /// A pointer to memory space that receives the strings of package full names that were found. - /// - /// - /// Type: UINT32* - /// A pointer to a variable that holds the number of characters in the string of package full names. - /// - /// First you pass NULL to buffer to get the number of characters. You use this number to allocate memory space for buffer. - /// Then you pass the address of this memory space to fill buffer. - /// - /// - /// - /// Type: WCHAR* - /// A pointer to memory space that receives the string of characters for all of the package full names. - /// - /// - /// Type: UINT32* - /// A pointer to memory space that receives the package properties for all of the packages that were found. - /// - /// - /// Type: LONG - /// - /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error - /// codes include the following. - /// - /// - /// - /// Return code - /// Description - /// - /// - /// ERROR_INSUFFICIENT_BUFFER - /// One or more buffer is not large enough to hold the data. The required size is specified by either count or buffer. - /// - /// - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-findpackagesbypackagefamily LONG - // FindPackagesByPackageFamily( PCWSTR packageFamilyName, UINT32 packageFilters, UINT32 *count, PWSTR *packageFullNames, UINT32 - // *bufferLength, WCHAR *buffer, UINT32 *packageProperties ); - [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true, CharSet = CharSet.Unicode)] - [PInvokeData("appmodel.h", MSDNShortId = "D52E98BD-726F-4AC0-A034-02896B1D1687")] - public static extern Win32Error FindPackagesByPackageFamily(string packageFamilyName, PACKAGE_FLAGS packageFilters, ref uint count, IntPtr packageFullNames, ref uint bufferLength, IntPtr buffer, IntPtr packageProperties); + /// + public APPX_PACKAGE_ARCHITECTURE processorArchitecture; /// - /// Constructs an application user model ID from the package family name and the package relative application ID (PRAID). - /// - /// - /// Type: PCWSTR - /// The package family name. - /// - /// - /// Type: PCWSTR - /// The package-relative app ID (PRAID). - /// - /// - /// Type: UINT32* - /// - /// A pointer to a variable that holds the number of characters ( WCHAR s) in the app user model ID string, which includes - /// the null-terminator. - /// - /// - /// First you pass NULL to applicationUserModelId to get the number of characters. You use this number to allocate memory - /// space for applicationUserModelId. Then you pass the address of this memory space to fill applicationUserModelId. - /// - /// - /// - /// Type: PWSTR - /// A pointer to memory space that receives the app user model ID string, which includes the null-terminator. - /// - /// - /// Type: LONG - /// - /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error - /// codes include the following. - /// - /// - /// - /// Return code - /// Description - /// - /// - /// ERROR_INVALID_PARAMETER - /// The packageFamilyName or packageRelativeApplicationId parameter isn't valid. - /// - /// - /// ERROR_INSUFFICIENT_BUFFER - /// - /// The buffer specified by applicationUserModelId is not large enough to hold the data; the required buffer size, in WCHARs, is - /// stored in the variable pointed to by applicationUserModelIdLength. - /// - /// - /// - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-formatapplicationusermodelid LONG - // FormatApplicationUserModelId( PCWSTR packageFamilyName, PCWSTR packageRelativeApplicationId, UINT32 - // *applicationUserModelIdLength, PWSTR applicationUserModelId ); - [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true, CharSet = CharSet.Unicode)] - [PInvokeData("appmodel.h", MSDNShortId = "F48D19C2-6373-41FC-A99D-E3CCB68D6C6C")] - public static extern Win32Error FormatApplicationUserModelId(string packageFamilyName, string packageRelativeApplicationId, - ref uint applicationUserModelIdLength, [Optional] StringBuilder applicationUserModelId); - - /// - /// Gets the application user model ID for the specified process. - /// - /// - /// - /// A handle to the process. This handle must have the PROCESS_QUERY_LIMITED_INFORMATION access right. For more info, see - /// Process Security and Access Rights. - /// - /// - /// - /// - /// On input, the size of the applicationUserModelId buffer, in wide characters. On success, the size of the buffer used, including - /// the null terminator. - /// - /// - /// - /// A pointer to a buffer that receives the application user model ID. - /// - /// - /// - /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error - /// codes include the following. - /// - /// - /// - /// Return code - /// Description - /// - /// - /// APPMODEL_ERROR_NO_APPLICATION - /// The process has no application identity. - /// - /// - /// ERROR_INSUFFICIENT_BUFFER - /// The buffer is not large enough to hold the data. The required size is specified by applicationUserModelIdLength. - /// - /// - /// - /// - /// For info about string size limits, see Identity constants. - /// Examples - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-getapplicationusermodelid LONG - // GetApplicationUserModelId( HANDLE hProcess, UINT32 *applicationUserModelIdLength, PWSTR applicationUserModelId ); - [DllImport(Lib.Kernel32, SetLastError = true, ExactSpelling = true)] - [PInvokeData("appmodel.h", MSDNShortId = "FE4E0818-F548-494B-B3BD-FB51DC748451")] - public static extern Win32Error GetApplicationUserModelId(HPROCESS hProcess, ref uint applicationUserModelIdLength, - [Optional, MarshalAs(UnmanagedType.LPWStr)] StringBuilder applicationUserModelId); - - /// - /// Gets the application user model ID for the specified token. - /// - /// - /// - /// A token that contains the application identity. This handle must have the PROCESS_QUERY_LIMITED_INFORMATION access right. - /// For more info, see Process Security and Access Rights. - /// - /// - /// - /// - /// On input, the size of the applicationUserModelId buffer, in wide characters. On success, the size of the buffer used, including - /// the null terminator. - /// - /// - /// - /// A pointer to a buffer that receives the application user model ID. - /// - /// - /// - /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error - /// codes include the following. - /// - /// - /// - /// Return code - /// Description - /// - /// - /// APPMODEL_ERROR_NO_APPLICATION - /// The token has no application identity. - /// - /// - /// ERROR_INSUFFICIENT_BUFFER - /// The buffer is not large enough to hold the data. The required size is specified by applicationUserModelIdLength. - /// - /// - /// - /// - /// For info about string size limits, see Identity constants. - /// Examples - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-getapplicationusermodelidfromtoken LONG - // GetApplicationUserModelIdFromToken( HANDLE token, UINT32 *applicationUserModelIdLength, PWSTR applicationUserModelId ); - [DllImport(Lib.KernelBase, SetLastError = true, ExactSpelling = true)] - [PInvokeData("appmodel.h", MSDNShortId = "80036518-927E-4CD0-B499-8EA472AB7E5A")] - public static extern Win32Error GetApplicationUserModelIdFromToken(HTOKEN token, ref uint applicationUserModelIdLength, - [Optional, MarshalAs(UnmanagedType.LPWStr)] StringBuilder applicationUserModelId); - - /// - /// Gets the application user model ID for the current process. - /// - /// - /// - /// On input, the size of the applicationUserModelId buffer, in wide characters. On success, the size of the buffer used, including - /// the null terminator. - /// - /// - /// - /// A pointer to a buffer that receives the application user model ID. - /// - /// - /// - /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error - /// codes include the following. - /// - /// - /// - /// Return code - /// Description - /// - /// - /// APPMODEL_ERROR_NO_APPLICATION - /// The process has no application identity. - /// - /// - /// ERROR_INSUFFICIENT_BUFFER - /// The buffer is not large enough to hold the data. The required size is specified by applicationUserModelIdLength. - /// - /// - /// - /// - /// For info about string size limits, see Identity constants. - /// Examples - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-getcurrentapplicationusermodelid LONG - // GetCurrentApplicationUserModelId( UINT32 *applicationUserModelIdLength, PWSTR applicationUserModelId ); - [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true, CharSet = CharSet.Unicode)] - [PInvokeData("appmodel.h", MSDNShortId = "562BB225-0922-4FE7-92C0-573A2CCE3195")] - public static extern Win32Error GetCurrentApplicationUserModelId(ref uint applicationUserModelIdLength, [Optional] StringBuilder applicationUserModelId); - - /// - /// Gets the package family name for the calling process. - /// - /// - /// Type: UINT32* - /// - /// On input, the size of the packageFamilyName buffer, in characters, including the null terminator. On output, the size of the - /// package family name returned, in characters, including the null terminator. - /// - /// - /// - /// Type: PWSTR - /// The package family name. - /// - /// - /// Type: LONG - /// - /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error - /// codes include the following. - /// - /// - /// - /// Return code - /// Description - /// - /// - /// APPMODEL_ERROR_NO_PACKAGE - /// The process has no package identity. - /// - /// - /// ERROR_INSUFFICIENT_BUFFER - /// The buffer is not large enough to hold the data. The required size is specified by packageFamilyNameLength. - /// - /// - /// - /// - /// For info about string size limits, see Identity constants. - /// Examples - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-getcurrentpackagefamilyname LONG - // GetCurrentPackageFamilyName( UINT32 *packageFamilyNameLength, PWSTR packageFamilyName ); - [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true, CharSet = CharSet.Unicode)] - [PInvokeData("appmodel.h", MSDNShortId = "39DBFBDD-A1CC-45C3-A5DD-5ED9697F9AFE")] - public static extern Win32Error GetCurrentPackageFamilyName(ref uint packageFamilyNameLength, [Optional] StringBuilder packageFamilyName); - - /// - /// Gets the package full name for the calling process. - /// - /// - /// Type: UINT32* - /// - /// On input, the size of the packageFullName buffer, in characters. On output, the size of the package full name returned, in - /// characters, including the null terminator. - /// - /// - /// - /// Type: PWSTR - /// The package full name. - /// - /// - /// Type: LONG - /// - /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error - /// codes include the following. - /// - /// - /// - /// Return code - /// Description - /// - /// - /// APPMODEL_ERROR_NO_PACKAGE - /// The process has no package identity. - /// - /// - /// ERROR_INSUFFICIENT_BUFFER - /// The buffer is not large enough to hold the data. The required size is specified by packageFullNameLength. - /// - /// - /// - /// - /// For info about string size limits, see Identity constants. - /// Examples - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-getcurrentpackagefullname LONG - // GetCurrentPackageFullName( UINT32 *packageFullNameLength, PWSTR packageFullName ); - [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true, CharSet = CharSet.Unicode)] - [PInvokeData("appmodel.h", MSDNShortId = "D5B00C53-1FBF-4245-92D1-FA39713A9EE7")] - public static extern Win32Error GetCurrentPackageFullName(ref uint packageFullNameLength, [Optional] StringBuilder packageFullName); - - /// - /// Gets the package identifier (ID) for the calling process. - /// - /// - /// Type: UINT32* - /// On input, the size of buffer, in bytes. On output, the size of the structure returned, in bytes. - /// - /// - /// Type: BYTE* - /// The package ID, represented as a PACKAGE_ID structure. - /// - /// - /// Type: LONG - /// - /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error - /// codes include the following. - /// - /// - /// - /// Return code - /// Description - /// - /// - /// APPMODEL_ERROR_NO_PACKAGE - /// The process has no package identity. - /// - /// - /// ERROR_INSUFFICIENT_BUFFER - /// The buffer is not large enough to hold the data. The required size is specified by bufferLength. - /// - /// - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-getcurrentpackageid LONG GetCurrentPackageId( UINT32 - // *bufferLength, BYTE *buffer ); - [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true)] - [PInvokeData("appmodel.h", MSDNShortId = "4CFC707A-2A5A-41FE-BB5F-6FECACC99271")] - public static extern Win32Error GetCurrentPackageId(ref uint bufferLength, IntPtr buffer); - - /// - /// Gets the package information for the calling process. - /// - /// - /// Type: const UINT32 - /// The package constants that specify how package information is retrieved. The PACKAGE_FILTER_* flags are supported. - /// - /// - /// Type: UINT32* - /// On input, the size of buffer, in bytes. On output, the size of the array of structures returned, in bytes. - /// - /// - /// Type: BYTE* - /// The package information, represented as an array of PACKAGE_INFO structures. - /// - /// - /// Type: UINT32* - /// The number of structures in the buffer. - /// - /// - /// Type: LONG - /// - /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error - /// codes include the following. - /// - /// - /// - /// Return code - /// Description - /// - /// - /// APPMODEL_ERROR_NO_PACKAGE - /// The process has no package identity. - /// - /// - /// ERROR_INSUFFICIENT_BUFFER - /// The buffer is not large enough to hold the data. The required size is specified by bufferLength. - /// - /// - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-getcurrentpackageinfo LONG GetCurrentPackageInfo( const - // UINT32 flags, UINT32 *bufferLength, BYTE *buffer, UINT32 *count ); - [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true)] - [PInvokeData("appmodel.h", MSDNShortId = "A1887D61-0FAD-4BE8-850F-F104CC074798")] - public static extern Win32Error GetCurrentPackageInfo(PACKAGE_FLAGS flags, ref uint bufferLength, IntPtr buffer, out uint count); - - /// - /// Gets the package information for the calling process, with the option to specify the type of folder path to retrieve for the package. - /// - /// - /// Type: const UINT32 - /// The package constants that specify how package information is retrieved. The PACKAGE_FILTER_* flags are supported. - /// - /// - /// Type: PackagePathType - /// Indicates the type of folder path to retrieve for the package (the original install folder or the mutable folder). - /// - /// - /// Type: UINT32* - /// On input, the size of buffer, in bytes. On output, the size of the array of structures returned, in bytes. - /// - /// - /// Type: BYTE* - /// The package information, represented as an array of PACKAGE_INFO structures. - /// - /// - /// Type: UINT32* - /// The number of structures in the buffer. - /// - /// - /// Type: LONG - /// - /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error - /// codes include the following. - /// - /// - /// - /// Return code - /// Description - /// - /// - /// APPMODEL_ERROR_NO_PACKAGE - /// The process has no package identity. - /// - /// - /// ERROR_INSUFFICIENT_BUFFER - /// The buffer is not large enough to hold the data. The required size is specified by bufferLength. - /// - /// - /// - /// - /// The packagePathType parameter is useful for applications that use the windows.mutablePackageDirectories extension in their - /// package manifest. This extension specifies a folder under the %ProgramFiles%\ModifiableWindowsApps path where the contents of - /// the application's install folder are projected so that users can modify the installation files. This feature is currently - /// available only for certain types of desktop PC games that are published by Microsoft and our partners, and it enables these - /// types of games to support mods. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/appmodel/nf-appmodel-getcurrentpackageinfo2 LONG GetCurrentPackageInfo2( const - // UINT32 flags, PackagePathType packagePathType, UINT32 *bufferLength, BYTE *buffer, UINT32 *count ); - [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true)] - [PInvokeData("appmodel.h")] - public static extern Win32Error GetCurrentPackageInfo2(PACKAGE_FLAGS flags, PackagePathType packagePathType, ref uint bufferLength, IntPtr buffer, out uint count); - - /// - /// Gets the package path for the calling process. - /// - /// - /// Type: UINT32* - /// - /// On input, the size of the path buffer, in characters. On output, the size of the package path returned, in characters, including - /// the null terminator. - /// - /// - /// - /// Type: PWSTR - /// The package path. - /// - /// - /// Type: LONG - /// - /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error - /// codes include the following. - /// - /// - /// - /// Return code - /// Description - /// - /// - /// APPMODEL_ERROR_NO_PACKAGE - /// The process has no package identity. - /// - /// - /// ERROR_INSUFFICIENT_BUFFER - /// The buffer is not large enough to hold the data. The required size is specified by pathLength. - /// - /// - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-getcurrentpackagepath LONG GetCurrentPackagePath( UINT32 - // *pathLength, PWSTR path ); - [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true, CharSet = CharSet.Unicode)] - [PInvokeData("appmodel.h", MSDNShortId = "46CE81DF-A9D5-492E-AB5E-4F043DC326E2")] - public static extern Win32Error GetCurrentPackagePath(ref uint pathLength, [Optional] StringBuilder path); - - /// - /// Gets the package path for the calling process, with the option to specify the type of folder path to retrieve for the package. - /// - /// - /// Type: PackagePathType - /// Indicates the type of folder path to retrieve for the package (the original install folder or the mutable folder). - /// - /// - /// Type: UINT32* - /// - /// On input, the size of the path buffer, in characters. On output, the size of the package path returned, in characters, including - /// the null terminator. - /// - /// - /// - /// Type: PWSTR - /// The package path. - /// - /// - /// Type: LONG - /// - /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error - /// codes include the following. - /// - /// - /// - /// Return code - /// Description - /// - /// - /// APPMODEL_ERROR_NO_PACKAGE - /// The process has no package identity. - /// - /// - /// ERROR_INSUFFICIENT_BUFFER - /// The buffer is not large enough to hold the data. The required size is specified by pathLength. - /// - /// - /// - /// - /// The packagePathType parameter is useful for applications that use the windows.mutablePackageDirectories extension in their - /// package manifest. This extension specifies a folder under the %ProgramFiles%\ModifiableWindowsApps path where the contents of - /// the application's install folder are projected so that users can modify the installation files. This feature is currently - /// available only for certain types of desktop PC games that are published by Microsoft and our partners, and it enables these - /// types of games to support mods. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/appmodel/nf-appmodel-getcurrentpackagepath2 LONG GetCurrentPackagePath2( - // PackagePathType packagePathType, UINT32 *pathLength, PWSTR path ); - [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true)] - [PInvokeData("appmodel.h")] - public static extern Win32Error GetCurrentPackagePath2(PackagePathType packagePathType, ref uint pathLength, - [Optional, MarshalAs(UnmanagedType.LPWStr)] StringBuilder path); - - /// Returns the package dependency for the specified context handle. - /// - /// Type: PACKAGEDEPENDENCY_CONTEXT - /// The handle of the package dependency to return. - /// - /// - /// Type: PCWSTR* - /// - /// The ID of the package dependency for the specified context handle. If the package dependency cannot be resolved, the function - /// succeeds but this parameter is nullptr on output. Use the HeapAlloc function to allocate memory for this parameter, and - /// use HeapFree to deallocate the memory. - /// - /// - /// - /// - /// - /// Return code - /// Description - /// - /// - /// E_INVALIDARG - /// The packageDependencyContext or packageDependencyId parameter is NULL on input. - /// - /// - /// - // https://docs.microsoft.com/gl-es/windows/win32/api/appmodel/nf-appmodel-getidforpackagedependencycontext - // HRESULT GetIdForPackageDependencyContext( PACKAGEDEPENDENCY_CONTEXT packageDependencyContext, PWSTR *packageDependencyId ); - [DllImport(Lib.KernelBase, SetLastError = false, ExactSpelling = true)] - [PInvokeData("appmodel.h", MSDNShortId = "NF:appmodel.GetIdForPackageDependencyContext")] - public static extern HRESULT GetIdForPackageDependencyContext(PACKAGEDEPENDENCY_CONTEXT packageDependencyContext, - out SafeHeapBlock packageDependencyId); - - /// - /// Gets the IDs of apps in the specified package. - /// - /// - /// Type: PACKAGE_INFO_REFERENCE - /// A reference to package information. - /// - /// - /// Type: UINT32* - /// A pointer to a variable that holds the size of buffer, in bytes. - /// - /// First you pass NULL to buffer to get the required size of buffer. You use this number to allocate memory space for - /// buffer. Then you pass the address of this memory space to fill buffer. - /// - /// - /// - /// Type: BYTE* - /// A pointer to memory space that receives the app IDs. - /// - /// - /// Type: UINT32* - /// A pointer to a variable that receives the number of app IDs in buffer. - /// - /// - /// Type: LONG - /// - /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error - /// codes include the following. - /// - /// - /// - /// Return code - /// Description - /// - /// - /// ERROR_INSUFFICIENT_BUFFER - /// The buffer is not large enough to hold the data. The required size is specified by bufferLength. - /// - /// - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-getpackageapplicationids LONG GetPackageApplicationIds( - // PACKAGE_INFO_REFERENCE packageInfoReference, UINT32 *bufferLength, BYTE *buffer, UINT32 *count ); - [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true)] - [PInvokeData("appmodel.h", MSDNShortId = "F08135F9-FF45-4309-84B5-77F4AFD7FC0C")] - public static extern Win32Error GetPackageApplicationIds(PACKAGE_INFO_REFERENCE packageInfoReference, ref uint bufferLength, IntPtr buffer, out uint count); - - /// - /// Gets the package family name for the specified process. - /// - /// - /// Type: HANDLE - /// - /// A handle to the process that has the PROCESS_QUERY_INFORMATION or PROCESS_QUERY_LIMITED_INFORMATION access right. - /// For more information, see Process Security and Access Rights. - /// - /// - /// - /// Type: UINT32* - /// - /// On input, the size of the packageFamilyName buffer, in characters. On output, the size of the package family name returned, in - /// characters, including the null-terminator. - /// - /// - /// - /// Type: PWSTR - /// The package family name. - /// - /// - /// Type: LONG - /// - /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error - /// codes include the following. - /// - /// - /// - /// Return code - /// Description - /// - /// - /// APPMODEL_ERROR_NO_PACKAGE - /// The process has no package identity. - /// - /// - /// ERROR_INSUFFICIENT_BUFFER - /// The buffer is not large enough to hold the data. The required size is specified by packageFamilyNameLength. - /// - /// - /// - /// - /// For info about string size limits, see Identity constants. - /// Examples - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-getpackagefamilyname LONG GetPackageFamilyName( HANDLE - // hProcess, UINT32 *packageFamilyNameLength, PWSTR packageFamilyName ); - [DllImport(Lib.Kernel32, SetLastError = true, ExactSpelling = true, CharSet = CharSet.Unicode)] - [PInvokeData("appmodel.h", MSDNShortId = "AC239898-9924-4193-9072-7A7EEC2D03E9")] - public static extern Win32Error GetPackageFamilyName(HPROCESS hProcess, ref uint packageFamilyNameLength, [Optional] StringBuilder packageFamilyName); - - /// - /// Gets the package family name for the specified token. - /// - /// - /// Type: HANDLE - /// A token that contains the package identity. - /// - /// - /// Type: UINT32* - /// - /// On input, the size of the packageFamilyName buffer, in characters. On output, the size of the package family name returned, in - /// characters, including the null-terminator. - /// - /// - /// - /// Type: PWSTR - /// The package family name. - /// - /// - /// Type: LONG - /// - /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error - /// codes include the following. - /// - /// - /// - /// Return code - /// Description - /// - /// - /// APPMODEL_ERROR_NO_PACKAGE - /// The token has no package identity. - /// - /// - /// ERROR_INSUFFICIENT_BUFFER - /// The buffer is not large enough to hold the data. The required size is specified by packageFamilyNameLength. - /// - /// - /// - /// - /// For info about string size limits, see Identity constants. - /// Examples - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-getpackagefamilynamefromtoken LONG - // GetPackageFamilyNameFromToken( HANDLE token, UINT32 *packageFamilyNameLength, PWSTR packageFamilyName ); - [DllImport(Lib.KernelBase, SetLastError = true, ExactSpelling = true, CharSet = CharSet.Unicode)] - [PInvokeData("appmodel.h", MSDNShortId = "C4FAF5DE-DF1F-4AFA-813B-5D80C786031B")] - public static extern Win32Error GetPackageFamilyNameFromToken(HTOKEN token, ref uint packageFamilyNameLength, [Optional] StringBuilder packageFamilyName); - - /// Gets the package full name for the specified process. - /// - /// Type: HANDLE - /// - /// A handle to the process that has the PROCESS_QUERY_INFORMATION or PROCESS_QUERY_LIMITED_INFORMATION access right. - /// For more information, see Process Security and Access Rights. - /// - /// - /// - /// Type: UINT32* - /// - /// On input, the size of the packageFullName buffer, in characters. On output, the size of the package full name returned, in - /// characters, including the null terminator. - /// - /// - /// - /// Type: PWSTR - /// The package full name. - /// - /// - /// Type: LONG - /// - /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error - /// codes include the following. - /// - /// - /// - /// Return code - /// Description - /// - /// - /// APPMODEL_ERROR_NO_PACKAGE - /// The process has no package identity. - /// - /// - /// ERROR_INSUFFICIENT_BUFFER - /// The buffer is not large enough to hold the data. The required size is specified by packageFullNameLength. - /// - /// - /// - /// - /// For info about string size limits, see Identity constants. - /// Examples - /// - /// #define _UNICODE 1 #define UNICODE 1 #include <Windows.h> #include <appmodel.h> #include <malloc.h> #include <stdlib.h> #include <stdio.h> int ShowUsage(); void ShowProcessPackageFullName(__in const UINT32 pid, __in HANDLE process); int ShowUsage() { wprintf(L"Usage: GetPackageFullName <pid> [<pid>...]\n"); return 1; } int __cdecl wmain(__in int argc, __in_ecount(argc) WCHAR * argv[]) { if (argc <= 1) return ShowUsage(); for (int i=1; i<argc; ++i) { UINT32 pid = wcstoul(argv[i], NULL, 10); if (pid > 0) { HANDLE process = OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION, FALSE, pid); if (process == NULL) wprintf(L"Error %d in OpenProcess (pid=%u)\n", GetLastError(), pid); else { ShowProcessPackageFullName(pid, process); CloseHandle(process); } } } return 0; } void ShowProcessPackageFullName(__in const UINT32 pid, __in HANDLE process) { wprintf(L"Process %u (handle=%p)\n", pid, process); UINT32 length = 0; LONG rc = GetPackageFullName(process, &length, NULL); if (rc != ERROR_INSUFFICIENT_BUFFER) { if (rc == APPMODEL_ERROR_NO_PACKAGE) wprintf(L"Process has no package identity\n"); else wprintf(L"Error %d in GetPackageFullName\n", rc); return; } PWSTR fullName = (PWSTR) malloc(length * sizeof(*fullName)); if (fullName == NULL) { wprintf(L"Error allocating memory\n"); return; } rc = GetPackageFullName(process, &length, fullName); if (rc != ERROR_SUCCESS) wprintf(L"Error %d retrieving PackageFullName\n", rc); else wprintf(L"%s\n", fullName); free(fullName); } - /// - /// - // https://webcache.googleusercontent.com/search?q=cache:IqzT6kD4rycJ:https://docs.microsoft.com/en-us/windows/win32/api/appmodel/nf-appmodel-getpackagefullname+&cd=2&hl=en&ct=clnk&gl=us - // LONG GetPackageFullName( HANDLE hProcess, UINT32 *packageFullNameLength, PWSTR packageFullName ); - [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true)] - [PInvokeData("appmodel.h", MSDNShortId = "NF:appmodel.GetPackageFullName")] - public static extern Win32Error GetPackageFullName(HPROCESS hProcess, ref uint packageFullNameLength, - [Optional, MarshalAs(UnmanagedType.LPWStr)] StringBuilder packageFullName); - - /// - /// Gets the package full name for the specified token. - /// - /// - /// A token that contains the package identity. - /// - /// - /// - /// On input, the size of the packageFullName buffer, in characters. On output, the size of the package full name returned, in - /// characters, including the null terminator. - /// - /// - /// - /// The package full name. - /// - /// - /// - /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error - /// codes include the following. - /// - /// - /// - /// Return code - /// Description - /// - /// - /// APPMODEL_ERROR_NO_PACKAGE - /// The token has no package identity. - /// - /// - /// ERROR_INSUFFICIENT_BUFFER - /// The buffer is not large enough to hold the data. The required size is specified by packageFullNameLength. - /// - /// - /// - /// - /// For info about string size limits, see Identity constants. - /// Examples - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-getpackagefullnamefromtoken LONG - // GetPackageFullNameFromToken( HANDLE token, UINT32 *packageFullNameLength, PWSTR packageFullName ); - [DllImport(Lib.KernelBase, SetLastError = false, ExactSpelling = true, CharSet = CharSet.Unicode)] - [PInvokeData("appmodel.h", MSDNShortId = "7B0D574E-A2F5-4D08-AEFB-9E040BBC729F")] - public static extern Win32Error GetPackageFullNameFromToken(HTOKEN token, ref uint packageFullNameLength, [Optional] StringBuilder packageFullName); - - /// - /// Gets the package information for the specified package. - /// - /// - /// Type: PACKAGE_INFO_REFERENCE - /// A reference to package information. - /// - /// - /// Type: const UINT32 - /// The package constants that specify how package information is retrieved. - /// - /// - /// Type: UINT32* - /// On input, the size of buffer, in bytes. On output, the size of the package information returned, in bytes. - /// - /// - /// Type: BYTE* - /// The package information, represented as an array of PACKAGE_INFO structures. - /// - /// - /// Type: UINT32* - /// The number of packages in the buffer. - /// - /// - /// Type: LONG - /// - /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error - /// codes include the following. - /// - /// - /// - /// Return code - /// Description - /// - /// - /// ERROR_INSUFFICIENT_BUFFER - /// The buffer is not large enough to hold the data. The required size is specified by bufferLength. - /// - /// - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-getpackageinfo LONG GetPackageInfo( - // PACKAGE_INFO_REFERENCE packageInfoReference, const UINT32 flags, UINT32 *bufferLength, BYTE *buffer, UINT32 *count ); - [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true)] - [PInvokeData("appmodel.h", MSDNShortId = "28F45B3B-A61F-44D3-B606-6966AD5866FA")] - public static extern Win32Error GetPackageInfo(PACKAGE_INFO_REFERENCE packageInfoReference, uint flags, ref uint bufferLength, IntPtr buffer, out uint count); - - /// - /// Gets the package information for the specified package, with the option to specify the type of folder path to retrieve for the package. - /// - /// - /// Type: PACKAGE_INFO_REFERENCE - /// A reference to package information. - /// - /// - /// Type: const UINT32 - /// The package constants that specify how package information is retrieved. - /// - /// - /// Type: PackagePathType - /// Indicates the type of folder path to retrieve for the package (the original install folder or the mutable folder). - /// - /// - /// Type: UINT32* - /// On input, the size of buffer, in bytes. On output, the size of the package information returned, in bytes. - /// - /// - /// Type: BYTE* - /// The package information, represented as an array of PACKAGE_INFO structures. - /// - /// - /// Type: UINT32* - /// The number of packages in the buffer. - /// - /// - /// Type: LONG - /// - /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error - /// codes include the following. - /// - /// - /// - /// Return code - /// Description - /// - /// - /// ERROR_INSUFFICIENT_BUFFER - /// The buffer is not large enough to hold the data. The required size is specified by bufferLength. - /// - /// - /// - /// - /// The packagePathType parameter is useful for applications that use the windows.mutablePackageDirectories extension in their - /// package manifest. This extension specifies a folder under the %ProgramFiles%\ModifiableWindowsApps path where the contents of - /// the application's install folder are projected so that users can modify the installation files. This feature is currently - /// available only for certain types of desktop PC games that are published by Microsoft and our partners, and it enables these - /// types of games to support mods. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/appmodel/nf-appmodel-getpackageinfo2 LONG GetPackageInfo2( - // PACKAGE_INFO_REFERENCE packageInfoReference, const UINT32 flags, PackagePathType packagePathType, UINT32 *bufferLength, BYTE - // *buffer, UINT32 *count ); - [DllImport(Lib.KernelBase, SetLastError = false, ExactSpelling = true)] - [PInvokeData("appmodel.h")] - public static extern Win32Error GetPackageInfo2(PACKAGE_INFO_REFERENCE packageInfoReference, uint flags, PackagePathType packagePathType, ref uint bufferLength, IntPtr buffer, out uint count); - - /// - /// Gets the path for the specified package. - /// - /// - /// Type: const PACKAGE_ID* - /// The package identifier. - /// - /// - /// Type: const UINT32 - /// Reserved, do not use. - /// - /// - /// Type: UINT32* - /// - /// On input, the size of the path buffer, in characters. On output, the size of the package path returned, in characters, including - /// the null-terminator. - /// - /// - /// - /// Type: PWSTR - /// The package path. - /// - /// - /// Type: LONG - /// - /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error - /// codes include the following. - /// - /// - /// - /// Return code - /// Description - /// - /// - /// ERROR_INSUFFICIENT_BUFFER - /// The buffer specified by path is not large enough to hold the data. The required size is specified by pathLength. - /// - /// - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-getpackagepath LONG GetPackagePath( const PACKAGE_ID - // *packageId, const UINT32 reserved, UINT32 *pathLength, PWSTR path ); - [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true, CharSet = CharSet.Unicode)] - [PInvokeData("appmodel.h", MSDNShortId = "BDA0DD87-A36D-486B-BF89-EA5CC105C742")] - public static extern Win32Error GetPackagePath(in PACKAGE_ID packageId, uint reserved, ref uint pathLength, [Optional] StringBuilder path); - - /// - /// Gets the path of the specified package. - /// - /// - /// Type: PCWSTR - /// The full name of the package. - /// - /// - /// Type: UINT32* - /// - /// A pointer to a variable that holds the number of characters ( WCHAR s) in the package path string, which includes the null-terminator. - /// - /// - /// First you pass NULL to path to get the number of characters. You use this number to allocate memory space for path. Then - /// you pass the address of this memory space to fill path. - /// - /// - /// - /// Type: PWSTR - /// A pointer to memory space that receives the package path string, which includes the null-terminator. - /// - /// - /// Type: LONG - /// - /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error - /// codes include the following. - /// - /// - /// - /// Return code - /// Description - /// - /// - /// ERROR_INSUFFICIENT_BUFFER - /// The buffer specified by path is not large enough to hold the data. The required size is specified by pathLength. - /// - /// - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-getpackagepathbyfullname LONG GetPackagePathByFullName( - // PCWSTR packageFullName, UINT32 *pathLength, PWSTR path ); - [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true, CharSet = CharSet.Unicode)] - [PInvokeData("appmodel.h", MSDNShortId = "9C25708C-1464-4C59-9740-E9F105116385")] - public static extern Win32Error GetPackagePathByFullName(string packageFullName, ref uint pathLength, [Optional] StringBuilder path); - - /// Gets the path of the specified package, with the option to specify the type of folder path to retrieve for the package. - /// - /// Type: PCWSTR - /// The full name of the package. - /// - /// - /// Type: PackagePathType - /// Indicates the type of folder path to retrieve for the package (the original install folder or the mutable folder). - /// - /// - /// Type: UINT32* - /// - /// A pointer to a variable that holds the number of characters ( WCHAR s) in the package path string, which includes the null-terminator. - /// - /// - /// First you pass NULL to path to get the number of characters. You use this number to allocate memory space for path. Then - /// you pass the address of this memory space to fill path. - /// - /// - /// - /// Type: PWSTR - /// A pointer to memory space that receives the package path string, which includes the null-terminator. - /// - /// - /// Type: LONG - /// - /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error - /// codes include the following. - /// - /// - /// - /// Return code - /// Description - /// - /// - /// ERROR_INSUFFICIENT_BUFFER - /// The buffer specified by path is not large enough to hold the data. The required size is specified by pathLength. - /// - /// - /// - /// - /// The packagePathType parameter is useful for applications that use the windows.mutablePackageDirectories extension in their - /// package manifest. This extension specifies a folder under the %ProgramFiles%\ModifiableWindowsApps path where the contents of - /// the application's install folder are projected so that users can modify the installation files. This feature is currently - /// available only for certain types of desktop PC games that are published by Microsoft and our partners, and it enables these - /// types of games to support mods. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/appmodel/nf-appmodel-getpackagepathbyfullname2 LONG GetPackagePathByFullName2( - // PCWSTR packageFullName, PackagePathType packagePathType, UINT32 *pathLength, PWSTR path ); - [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true)] - [PInvokeData("appmodel.h")] - public static extern Win32Error GetPackagePathByFullName2([MarshalAs(UnmanagedType.LPWStr)] string packageFullName, PackagePathType packagePathType, - ref uint pathLength, [Optional, MarshalAs(UnmanagedType.LPWStr)] StringBuilder path); - - /// - /// Gets the packages with the specified family name for the current user. - /// - /// - /// Type: PCWSTR - /// The package family name. - /// - /// - /// Type: UINT32* - /// A pointer to a variable that holds the number of package full names. - /// - /// First you pass NULL to packageFullNames to get the number of package full names. You use this number to allocate memory - /// space for packageFullNames. Then you pass the address of this number to fill packageFullNames. - /// - /// - /// - /// Type: PWSTR* - /// A pointer to the strings of package full names. - /// - /// - /// Type: UINT32* - /// A pointer to a variable that holds the number of characters in the string of package full names. - /// - /// First you pass NULL to buffer to get the number of characters. You use this number to allocate memory space for buffer. - /// Then you pass the address of this number to fill buffer. - /// - /// - /// - /// Type: WCHAR* - /// The string of characters for all of the package full names. - /// - /// - /// Type: LONG - /// - /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error - /// codes include the following. - /// - /// - /// - /// Return code - /// Description - /// - /// - /// ERROR_INSUFFICIENT_BUFFER - /// One or more buffer is not large enough to hold the data. The required size is specified by either count or buffer. - /// - /// - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-getpackagesbypackagefamily LONG - // GetPackagesByPackageFamily( PCWSTR packageFamilyName, UINT32 *count, PWSTR *packageFullNames, UINT32 *bufferLength, WCHAR *buffer ); - [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true, CharSet = CharSet.Unicode)] - [PInvokeData("appmodel.h", MSDNShortId = "C2163203-D654-4491-9090-0CC43F42EC35")] - public static extern Win32Error GetPackagesByPackageFamily(string packageFamilyName, ref uint count, [Out, MarshalAs(UnmanagedType.LPArray, ArraySubType = UnmanagedType.LPWStr, SizeParamIndex = 1)] string[] packageFullNames, ref uint bufferLength, IntPtr buffer); - - /// - /// Gets the origin of the specified package. - /// - /// - /// Type: PCWSTR - /// The full name of the package. - /// - /// - /// Type: PackageOrigin* - /// - /// A pointer to a variable that receives a PackageOrigin-typed value that indicates the origin of the package specified by packageFullName. - /// - /// - /// - /// Type: LONG - /// - /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error - /// codes include the following. - /// - /// - /// - /// Return code - /// Description - /// - /// - /// ERROR_INVALID_PARAMETER - /// The packageFullName parameter isn't valid. - /// - /// - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-getstagedpackageorigin LONG GetStagedPackageOrigin( - // PCWSTR packageFullName, PackageOrigin *origin ); - [DllImport(Lib.KernelBase, SetLastError = false, ExactSpelling = true, CharSet = CharSet.Unicode)] - [PInvokeData("appmodel.h", MSDNShortId = "7A1EE2CA-83CE-4E03-85A5-0061E29EB49B")] - public static extern Win32Error GetStagedPackageOrigin(string packageFullName, out PackageOrigin origin); - - /// - /// Gets the path of the specified staged package. - /// - /// - /// Type: PCWSTR - /// The full name of the staged package. - /// - /// - /// Type: UINT32* - /// - /// A pointer to a variable that holds the number of characters ( WCHAR s) in the package path string, which includes the null-terminator. - /// - /// - /// First you pass NULL to path to get the number of characters. You use this number to allocate memory space for path. Then - /// you pass the address of this memory space to fill path. - /// - /// - /// - /// Type: PWSTR - /// A pointer to memory space that receives the package path string, which includes the null-terminator. - /// - /// - /// Type: LONG - /// - /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error - /// codes include the following. - /// - /// - /// - /// Return code - /// Description - /// - /// - /// ERROR_INSUFFICIENT_BUFFER - /// The buffer specified by path is not large enough to hold the data. The required size is specified by pathLength. - /// - /// - /// - /// - /// - /// This function succeeds if the package is staged, regardless of the user context or if the package is registered for the current user. - /// - /// Examples - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-getstagedpackagepathbyfullname LONG - // GetStagedPackagePathByFullName( PCWSTR packageFullName, UINT32 *pathLength, PWSTR path ); - [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true)] - [PInvokeData("appmodel.h", MSDNShortId = "F0A37D77-6262-44B1-BEC5-083E41BDE139")] - public static extern Win32Error GetStagedPackagePathByFullName([MarshalAs(UnmanagedType.LPWStr)] string packageFullName, ref uint pathLength, - [Optional, MarshalAs(UnmanagedType.LPWStr)] StringBuilder path); - - /// - /// Gets the path of the specified staged package, with the option to specify the type of folder path to retrieve for the package. - /// - /// - /// Type: PCWSTR - /// The full name of the staged package. - /// - /// - /// Type: PackagePathType - /// Indicates the type of folder path to retrieve for the package (the original install folder or the mutable folder). - /// - /// - /// Type: UINT32* - /// - /// A pointer to a variable that holds the number of characters ( WCHAR s) in the package path string, which includes the null-terminator. - /// - /// - /// First you pass NULL to path to get the number of characters. You use this number to allocate memory space for path. Then - /// you pass the address of this memory space to fill path. - /// - /// - /// - /// Type: PWSTR - /// A pointer to memory space that receives the package path string, which includes the null-terminator. - /// - /// - /// Type: LONG - /// - /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error - /// codes include the following. - /// - /// - /// - /// Return code - /// Description - /// - /// - /// ERROR_INSUFFICIENT_BUFFER - /// The buffer specified by path is not large enough to hold the data. The required size is specified by pathLength. - /// - /// - /// - /// - /// The packagePathType parameter is useful for applications that use the windows.mutablePackageDirectories extension in their - /// package manifest. This extension specifies a folder under the %ProgramFiles%\ModifiableWindowsApps path where the contents of - /// the application's install folder are projected so that users can modify the installation files. This feature is currently - /// available only for certain types of desktop PC games that are published by Microsoft and our partners, and it enables these - /// types of games to support mods. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/appmodel/nf-appmodel-getstagedpackagepathbyfullname2 LONG - // GetStagedPackagePathByFullName2( PCWSTR packageFullName, PackagePathType packagePathType, UINT32 *pathLength, PWSTR path ); - [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true)] - [PInvokeData("appmodel.h")] - public static extern Win32Error GetStagedPackagePathByFullName2([MarshalAs(UnmanagedType.LPWStr)] string packageFullName, PackagePathType packagePathType, - ref uint pathLength, [Optional, MarshalAs(UnmanagedType.LPWStr)] StringBuilder path); - - /// - /// Opens the package information of the specified package. - /// - /// - /// Type: PCWSTR - /// The full name of the package. - /// - /// - /// Type: const UINT32 - /// Reserved; must be 0. - /// - /// - /// Type: PACKAGE_INFO_REFERENCE* - /// A reference to package information. - /// - /// - /// Type: LONG - /// - /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error - /// codes include the following. - /// - /// - /// - /// Return code - /// Description - /// - /// - /// ERROR_NOT_FOUND - /// The package is not installed for the current user. - /// - /// - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-openpackageinfobyfullname LONG - // OpenPackageInfoByFullName( PCWSTR packageFullName, const UINT32 reserved, PACKAGE_INFO_REFERENCE *packageInfoReference ); - [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true)] - [PInvokeData("appmodel.h", MSDNShortId = "9ECFC757-1CB3-43A1-BA45-9AF72CAB240E")] - public static extern Win32Error OpenPackageInfoByFullName([MarshalAs(UnmanagedType.LPWStr)] string packageFullName, uint reserved, ref PACKAGE_INFO_REFERENCE packageInfoReference); - - /// - /// Gets the package family name for the specified package full name. - /// - /// - /// Type: PCWSTR - /// The full name of a package. - /// - /// - /// Type: UINT32* - /// - /// On input, the size of the packageFamilyName buffer, in characters. On output, the size of the package family name returned, in - /// characters, including the null terminator. - /// - /// - /// - /// Type: PWSTR - /// The package family name. - /// - /// - /// Type: LONG - /// - /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error - /// codes include the following. - /// - /// - /// - /// Return code - /// Description - /// - /// - /// ERROR_INSUFFICIENT_BUFFER - /// The buffer is not large enough to hold the data. The required size is specified by packageFamilyNameLength. - /// - /// - /// - /// - /// For info about string size limits, see Identity constants. - /// Examples - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-packagefamilynamefromfullname LONG - // PackageFamilyNameFromFullName( PCWSTR packageFullName, UINT32 *packageFamilyNameLength, PWSTR packageFamilyName ); - [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true, CharSet = CharSet.Unicode)] - [PInvokeData("appmodel.h", MSDNShortId = "98E95CE5-E970-4A19-BAD3-994DAEC4BEA0")] - public static extern Win32Error PackageFamilyNameFromFullName(string packageFullName, ref uint packageFamilyNameLength, - [Optional] StringBuilder packageFamilyName); - - /// - /// Gets the package family name for the specified package identifier. - /// - /// - /// Type: const PACKAGE_ID* - /// The package identifier. - /// - /// - /// Type: UINT32* - /// - /// On input, the size of the packageFamilyName buffer, in characters. On output, the size of the package family name returned, in - /// characters, including the null terminator. - /// - /// - /// - /// Type: PWSTR - /// The package family name. - /// - /// - /// Type: LONG - /// - /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error - /// codes include the following. - /// - /// - /// - /// Return code - /// Description - /// - /// - /// ERROR_INSUFFICIENT_BUFFER - /// The buffer is not large enough to hold the data. The required size is specified by packageFamilyNameLength. - /// - /// - /// - /// - /// For info about string size limits, see Identity constants. - /// Examples - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-packagefamilynamefromid LONG PackageFamilyNameFromId( - // const PACKAGE_ID *packageId, UINT32 *packageFamilyNameLength, PWSTR packageFamilyName ); - [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true)] - [PInvokeData("appmodel.h", MSDNShortId = "198DAB6B-21D2-4ACB-87DF-B3F4EFBEE323")] - public static extern Win32Error PackageFamilyNameFromId(in PACKAGE_ID packageId, ref uint packageFamilyNameLength, - [Optional, MarshalAs(UnmanagedType.LPWStr)] StringBuilder packageFamilyName); - - /// - /// Gets the package full name for the specified package identifier (ID). - /// - /// - /// Type: const PACKAGE_ID* - /// The package ID. - /// - /// - /// Type: UINT32* - /// - /// On input, the size of the packageFullName buffer, in characters. On output, the size of the package full name returned, in - /// characters, including the null terminator. - /// - /// - /// - /// Type: PWSTR - /// The package full name. - /// - /// - /// Type: LONG - /// - /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error - /// codes include the following. - /// - /// - /// - /// Return code - /// Description - /// - /// - /// ERROR_INSUFFICIENT_BUFFER - /// The buffer is not large enough to hold the data. The required size is specified by packageFullNameLength. - /// - /// - /// - /// - /// For info about string size limits, see Identity constants. - /// Examples - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-packagefullnamefromid LONG PackageFullNameFromId( const - // PACKAGE_ID *packageId, UINT32 *packageFullNameLength, PWSTR packageFullName ); - [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true)] - [PInvokeData("appmodel.h", MSDNShortId = "0024AF55-295E-49B1-90C2-9144D336529B")] - public static extern Win32Error PackageFullNameFromId(in PACKAGE_ID packageId, ref uint packageFullNameLength, - [Optional, MarshalAs(UnmanagedType.LPWStr)] StringBuilder packageFullName); - - /// - /// Gets the package identifier (ID) for the specified package full name. - /// - /// - /// Type: PCWSTR - /// The full name of a package. - /// - /// - /// Type: const UINT32 - /// The package constants that specify how package information is retrieved. The PACKAGE_INFORMATION_* flags are supported. - /// - /// - /// Type: UINT32* - /// On input, the size of buffer, in bytes. On output, the size of the data returned, in bytes. - /// - /// - /// Type: BYTE* - /// The package ID, represented as a PACKAGE_ID structure. - /// - /// - /// Type: LONG - /// - /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error - /// codes include the following. - /// - /// - /// - /// Return code - /// Description - /// - /// - /// ERROR_INSUFFICIENT_BUFFER - /// The buffer is not large enough to hold the data. The required size is specified by bufferLength. - /// - /// - /// ERROR_NOT_FOUND - /// The package is not installed for the user. - /// - /// - /// - /// - /// If flags specifies PACKAGE_INFORMATION_BASIC, the following fields are retrieved: - /// - /// - /// name - /// - /// - /// processorArchitecture - /// - /// - /// publisherId - /// - /// - /// resourceId - /// - /// - /// version - /// - /// - /// If flags specifies PACKAGE_INFORMATION_FULL, the following fields are retrieved: - /// - /// - /// name - /// - /// - /// processorArchitecture - /// - /// - /// publisher - /// - /// - /// publisherId - /// - /// - /// resourceId - /// - /// - /// version - /// - /// - /// - /// A request for PACKAGE_INFORMATION_FULL succeeds only if the package corresponding to packageFullName is installed for and - /// accessible to the current user. If the package full name is syntactically correct but does not correspond to a package that is - /// installed for and accessible to the current user, the function returns ERROR_NOT_FOUND. - /// - /// For info about string size limits, see Identity constants. - /// Examples - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-packageidfromfullname LONG PackageIdFromFullName( - // PCWSTR packageFullName, const UINT32 flags, UINT32 *bufferLength, BYTE *buffer ); - [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true)] - [PInvokeData("appmodel.h", MSDNShortId = "EED832F8-E4F7-4A0F-93E2-451F78F67767")] - public static extern Win32Error PackageIdFromFullName([MarshalAs(UnmanagedType.LPWStr)] string packageFullName, PACKAGE_FLAGS flags, ref uint bufferLength, IntPtr buffer); - - /// - /// Gets the package name and publisher identifier (ID) for the specified package family name. - /// - /// - /// Type: PCWSTR - /// The family name of a package. - /// - /// - /// Type: UINT32* - /// - /// On input, the size of the packageName buffer, in characters. On output, the size of the package name returned, in characters, - /// including the null-terminator. - /// - /// - /// - /// Type: PWSTR - /// The package name. - /// - /// - /// Type: UINT32* - /// - /// On input, the size of the packagePublishId buffer, in characters. On output, the size of the publisher ID returned, in - /// characters, including the null-terminator. - /// - /// - /// - /// Type: PWSTR - /// The package publisher ID. - /// - /// - /// Type: LONG - /// - /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error - /// codes include the following. - /// - /// - /// - /// Return code - /// Description - /// - /// - /// ERROR_INSUFFICIENT_BUFFER - /// One of the buffers is not large enough to hold the data. The required sizes are specified by packageNameLength and packagePublisherIdLength. - /// - /// - /// - /// - /// For info about string size limits, see Identity constants. - /// Examples - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-packagenameandpublisheridfromfamilyname LONG - // PackageNameAndPublisherIdFromFamilyName( PCWSTR packageFamilyName, UINT32 *packageNameLength, PWSTR packageName, UINT32 - // *packagePublisherIdLength, PWSTR packagePublisherId ); - [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true, CharSet = CharSet.Unicode)] - [PInvokeData("appmodel.h", MSDNShortId = "4AA5BD75-F865-40D6-9C10-E54C197D47C4")] - public static extern Win32Error PackageNameAndPublisherIdFromFamilyName(string packageFamilyName, ref uint packageNameLength, - [Optional] StringBuilder packageName, ref uint packagePublisherIdLength, [Optional] StringBuilder packagePublisherId); - - /// - /// Deconstructs an application user model ID to its package family name and package relative application ID (PRAID). - /// - /// - /// Type: PCWSTR - /// The app user model ID. - /// - /// - /// Type: UINT32* - /// - /// A pointer to a variable that holds the number of characters ( WCHAR s) in the package family name string, which includes - /// the null-terminator. - /// - /// - /// First you pass NULL to packageFamilyName to get the number of characters. You use this number to allocate memory space - /// for packageFamilyName. Then you pass the address of this memory space to fill packageFamilyName. - /// - /// - /// - /// Type: PWSTR - /// A pointer to memory space that receives the package family name string, which includes the null-terminator. - /// - /// - /// Type: UINT32* - /// - /// A pointer to a variable that holds the number of characters ( WCHAR s) in the package-relative app ID string, which - /// includes the null-terminator. - /// - /// - /// First you pass NULL to packageRelativeApplicationId to get the number of characters. You use this number to allocate - /// memory space for packageRelativeApplicationId. Then you pass the address of this memory space to fill packageRelativeApplicationId. - /// - /// - /// - /// Type: PWSTR - /// A pointer to memory space that receives the package-relative app ID (PRAID) string, which includes the null-terminator. - /// - /// - /// Type: LONG - /// - /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error - /// codes include the following. - /// - /// - /// - /// Return code - /// Description - /// - /// - /// ERROR_INVALID_PARAMETER - /// The applicationUserModelId parameter isn't valid. - /// - /// - /// ERROR_INSUFFICIENT_BUFFER - /// - /// The buffer specified by packageFamilyName or packageRelativeApplicationId is not large enough to hold the data; the required - /// buffer size, in WCHARs, is stored in the variable pointed to by packageFamilyNameLength or packageRelativeApplicationIdLength. - /// - /// - /// - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/nf-appmodel-parseapplicationusermodelid LONG - // ParseApplicationUserModelId( PCWSTR applicationUserModelId, UINT32 *packageFamilyNameLength, PWSTR packageFamilyName, UINT32 - // *packageRelativeApplicationIdLength, PWSTR packageRelativeApplicationId ); - [DllImport(Lib.Kernel32, SetLastError = false, ExactSpelling = true, CharSet = CharSet.Unicode)] - [PInvokeData("appmodel.h", MSDNShortId = "03B29E82-611F-47D1-8CB6-047B9BEB4D9E")] - public static extern Win32Error ParseApplicationUserModelId(string applicationUserModelId, ref uint packageFamilyNameLength, - [Optional] StringBuilder packageFamilyName, ref uint packageRelativeApplicationIdLength, [Optional] StringBuilder packageRelativeApplicationId); - - /// - /// Removes a resolved package dependency from the current process' package graph (that is, a run-time reference for a framework - /// package dependency that was added by using the AddPackageDependency method). - /// - /// - /// Type: PACKAGEDEPENDENCY_CONTEXT - /// The handle of the package dependency to remove. - /// - /// - /// Type: HRESULT - /// - /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error - /// codes include the following. - /// - /// - /// - /// Return code - /// Description - /// - /// - /// E_INVALIDARG - /// The packageDependencyContext parameter is NULL on input. - /// - /// - /// - /// - /// This function does not unload loaded resources such as DLLs. After removing a package dependency, any files loaded from the - /// package can continue to be used. Future file resolution will fail to see the removed package dependency. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/appmodel/nf-appmodel-removepackagedependency HRESULT RemovePackageDependency( - // PACKAGEDEPENDENCY_CONTEXT packageDependencyContext ); - [DllImport(Lib.KernelBase, SetLastError = false, ExactSpelling = true)] - [PInvokeData("appmodel.h", MSDNShortId = "NF:appmodel.RemovePackageDependency")] - public static extern HRESULT RemovePackageDependency([In] PACKAGEDEPENDENCY_CONTEXT packageDependencyContext); - - /// Creates an install-time reference for a framework package dependency for the current app, using the specified package family name, minimum version, and additional criteria. - /// - /// Type: PSID - /// The user scope of the package dependency. If NULL, the caller's user context is used. Must be NULL if CreatePackageDependencyOptions_ScopeIsSystem is specified. - /// - /// - /// Type: PCWSTR - /// The package family name of the framework package on which to take dependency. - /// - /// /// Type: PACKAGE_VERSION - /// The minimum version of the framework package on which to take dependency. - /// - /// - /// Type: PackageDependencyProcessorArchitectures - /// The processor architectures of the package dependency. - /// - /// - /// Type: PackageDependencyLifetimeKind - /// The type of artifact to use to define the lifetime of the package dependency. For more information, see the remarks. - /// - /// - /// Type: PCWSTR - /// The name of the artifact used to define the lifetime of the package dependency. Must be NULL if the lifetimeKind parameter is PackageDependencyLifetimeKind_Process. For more information, see the remarks. - /// - /// - /// Type: CreatePackageDependencyOptions - /// The options to apply when creating the package dependency. - /// - /// - /// Type: PWSTR* - /// The ID of the new package dependency. Use the HeapAlloc function to allocate memory for this parameter, and use HeapFree to deallocate the memory. - /// - /// - /// Type: HRESULT - /// If the function succeeds it returns ERROR_SUCCESS. Otherwise, the function returns an error code. The possible error codes include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// E_INVALIDARG - /// The packageDependencyId parameter is NULL on input. - /// - /// - /// - /// - /// In your app's installer or during the first run of your app, call this method to specify a set of criteria for a framework package you want to use in your app. This informs the OS that your app has a dependency upon a framework package that meets the specified criteria. If one or more framework packages are installed that meet the criteria, Windows will ensure that at least one of these framework packages will remain installed until the install-time reference is deleted. For more information, see Use the dynamic dependency API to reference framework packages at run time. - /// This function fails if the specified dependency criteria cannot be resolved to a specific package. This package resolution check is skipped if CreatePackageDependencyOptions_DoNotVerifyDependencyResolution is specified for the options parameter. This is useful for installers running as user contexts other than the target user (for example, installers running as LocalSystem). - /// - // https://docs.microsoft.com/en-us/windows/win32/api/appmodel/nf-appmodel-trycreatepackagedependency - // HRESULT TryCreatePackageDependency( PSID user, PCWSTR packageFamilyName, PACKAGE_VERSION minVersion, PackageDependencyProcessorArchitectures packageDependencyProcessorArchitectures, PackageDependencyLifetimeKind lifetimeKind, PCWSTR lifetimeArtifact, CreatePackageDependencyOptions options, PWSTR *packageDependencyId ); - [DllImport(Lib.KernelBase, SetLastError = false, ExactSpelling = true)] - [PInvokeData("appmodel.h", MSDNShortId = "NF:appmodel.TryCreatePackageDependency")] - public static extern HRESULT TryCreatePackageDependency([In, Optional] PSID user, [MarshalAs(UnmanagedType.LPWStr)] string packageFamilyName, - PACKAGE_VERSION minVersion, PackageDependencyProcessorArchitectures packageDependencyProcessorArchitectures, - PackageDependencyLifetimeKind lifetimeKind, [MarshalAs(UnmanagedType.LPWStr)] string lifetimeArtifact, - CreatePackageDependencyOptions options, out SafeHeapBlock packageDependencyId); + /// The version of the package. + /// + public PACKAGE_VERSION version; /// - /// Represents package identification information, such as name, version, and publisher. + /// Type: PWSTR + /// The name of the package. /// - /// - /// For info about string size limits, see Identity constants. - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/ns-appmodel-package_id typedef struct PACKAGE_ID { UINT32 reserved; - // UINT32 processorArchitecture; PACKAGE_VERSION version; PWSTR name; PWSTR publisher; PWSTR resourceId; PWSTR publisherId; }; - [PInvokeData("appmodel.h", MSDNShortId = "4B15281A-2227-47B7-A750-0A01DB8543FC")] - [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)] - public struct PACKAGE_ID - { - /// - /// Type: UINT32 - /// Reserved; do not use. - /// - public uint reserved; - - /// - /// Type: UINT32 - /// - /// The processor architecture of the package. This member must be one of the values of the APPX_PACKAGE_ARCHITECTURE enumeration. - /// - /// - public APPX_PACKAGE_ARCHITECTURE processorArchitecture; - - /// - /// Type: PACKAGE_VERSION - /// The version of the package. - /// - public PACKAGE_VERSION version; - - /// - /// Type: PWSTR - /// The name of the package. - /// - public string name; - - /// - /// Type: PWSTR - /// The publisher of the package. If there is no publisher for the package, this member is NULL. - /// - public string publisher; - - /// - /// Type: PWSTR - /// The resource identifier (ID) of the package. If there is no resource ID for the package, this member is NULL. - /// - public string resourceId; - - /// - /// Type: PWSTR - /// The publisher identifier (ID) of the package. If there is no publisher ID for the package, this member is NULL. - /// - public string publisherId; - } - - /// Represents package identification information that includes the package identifier, full name, and install location. - /// For info about string size limits, see Identity constants. - // https://docs.microsoft.com/en-us/windows/win32/api/appmodel/ns-appmodel-package_info typedef struct PACKAGE_INFO { UINT32 - // reserved; UINT32 flags; PWSTR path; PWSTR packageFullName; PWSTR packageFamilyName; PACKAGE_ID packageId; } PACKAGE_INFO; - [PInvokeData("appmodel.h", MSDNShortId = "0DDE00D1-9C5F-4F2B-8110-A92B1FFA1B64")] - [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)] - public struct PACKAGE_INFO - { - /// Reserved; do not use. - public uint reserved; - - /// Properties of the package. - public uint flags; - - /// The location of the package. - [MarshalAs(UnmanagedType.LPWStr)] public string path; - - /// The package full name/ - [MarshalAs(UnmanagedType.LPWStr)] public string packageFullName; - - /// The package family name. - [MarshalAs(UnmanagedType.LPWStr)] public string packageFamilyName; - - /// The package identifier (ID). - public PACKAGE_ID packageId; - } - - /// A reference to package information. - [PInvokeData("appmodel.h")] - [StructLayout(LayoutKind.Sequential)] - public struct PACKAGE_INFO_REFERENCE - { - /// Reserved. - public IntPtr reserved; - } + public string name; /// - /// Represents the package version information. + /// Type: PWSTR + /// The publisher of the package. If there is no publisher for the package, this member is NULL. /// - // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/ns-appmodel-package_version typedef struct PACKAGE_VERSION { union - // { UINT64 Version; struct { USHORT Revision; USHORT Build; USHORT Minor; USHORT Major; } DUMMYSTRUCTNAME; } DUMMYUNIONNAME; }; - [PInvokeData("appmodel.h", MSDNShortId = "8543DF84-A908-4DF5-AEE6-169FECB2AA97")] - [StructLayout(LayoutKind.Explicit)] - public struct PACKAGE_VERSION + public string publisher; + + /// + /// Type: PWSTR + /// The resource identifier (ID) of the package. If there is no resource ID for the package, this member is NULL. + /// + public string resourceId; + + /// + /// Type: PWSTR + /// The publisher identifier (ID) of the package. If there is no publisher ID for the package, this member is NULL. + /// + public string publisherId; + } + + /// Represents package identification information that includes the package identifier, full name, and install location. + /// For info about string size limits, see Identity constants. + // https://docs.microsoft.com/en-us/windows/win32/api/appmodel/ns-appmodel-package_info typedef struct PACKAGE_INFO { UINT32 + // reserved; UINT32 flags; PWSTR path; PWSTR packageFullName; PWSTR packageFamilyName; PACKAGE_ID packageId; } PACKAGE_INFO; + [PInvokeData("appmodel.h", MSDNShortId = "0DDE00D1-9C5F-4F2B-8110-A92B1FFA1B64")] + [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)] + public struct PACKAGE_INFO + { + /// Reserved; do not use. + public uint reserved; + + /// Properties of the package. + public uint flags; + + /// The location of the package. + [MarshalAs(UnmanagedType.LPWStr)] public string path; + + /// The package full name/ + [MarshalAs(UnmanagedType.LPWStr)] public string packageFullName; + + /// The package family name. + [MarshalAs(UnmanagedType.LPWStr)] public string packageFamilyName; + + /// The package identifier (ID). + public PACKAGE_ID packageId; + } + + /// A reference to package information. + [PInvokeData("appmodel.h")] + [StructLayout(LayoutKind.Sequential)] + public struct PACKAGE_INFO_REFERENCE + { + /// Reserved. + public IntPtr reserved; + } + + /// + /// Represents the package version information. + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/appmodel/ns-appmodel-package_version typedef struct PACKAGE_VERSION { union + // { UINT64 Version; struct { USHORT Revision; USHORT Build; USHORT Minor; USHORT Major; } DUMMYSTRUCTNAME; } DUMMYUNIONNAME; }; + [PInvokeData("appmodel.h", MSDNShortId = "8543DF84-A908-4DF5-AEE6-169FECB2AA97")] + [StructLayout(LayoutKind.Explicit)] + public struct PACKAGE_VERSION + { + /// + /// Type: UINT64 + /// The full version number of the package represented as a single integral value. + /// + [FieldOffset(0)] + public ulong Version; + + /// Parts of the Version. + [FieldOffset(0)] + public DUMMYSTRUCTNAME Parts; + + /// Parts of the Version. + public struct DUMMYSTRUCTNAME { /// - /// Type: UINT64 - /// The full version number of the package represented as a single integral value. + /// Type: USHORT + /// The revision version number of the package. /// - [FieldOffset(0)] - public ulong Version; + public ushort Revision; - /// Parts of the Version. - [FieldOffset(0)] - public DUMMYSTRUCTNAME Parts; + /// + /// Type: USHORT + /// The build version number of the package. + /// + public ushort Build; - /// Parts of the Version. - public struct DUMMYSTRUCTNAME - { - /// - /// Type: USHORT - /// The revision version number of the package. - /// - public ushort Revision; + /// + /// Type: USHORT + /// The minor version number of the package. + /// + public ushort Minor; - /// - /// Type: USHORT - /// The build version number of the package. - /// - public ushort Build; - - /// - /// Type: USHORT - /// The minor version number of the package. - /// - public ushort Minor; - - /// - /// Type: USHORT - /// The major version number of the package. - /// - public ushort Major; - } - } - - /// Provides a handle to a package dependency context. - [PInvokeData("appmodel.h")] - [StructLayout(LayoutKind.Sequential)] - public struct PACKAGEDEPENDENCY_CONTEXT : IHandle - { - private readonly IntPtr handle; - - /// Initializes a new instance of the struct. - /// An object that represents the pre-existing handle to use. - public PACKAGEDEPENDENCY_CONTEXT(IntPtr preexistingHandle) => handle = preexistingHandle; - - /// Returns an invalid handle by instantiating a object with . - public static PACKAGEDEPENDENCY_CONTEXT NULL => new(IntPtr.Zero); - - /// Gets a value indicating whether this instance is a null handle. - public bool IsNull => handle == IntPtr.Zero; - - /// Performs an explicit conversion from to . - /// The handle. - /// The result of the conversion. - public static explicit operator IntPtr(PACKAGEDEPENDENCY_CONTEXT h) => h.handle; - - /// Performs an implicit conversion from to . - /// The pointer to a handle. - /// The result of the conversion. - public static implicit operator PACKAGEDEPENDENCY_CONTEXT(IntPtr h) => new(h); - - /// Implements the operator !=. - /// The first handle. - /// The second handle. - /// The result of the operator. - public static bool operator !=(PACKAGEDEPENDENCY_CONTEXT h1, PACKAGEDEPENDENCY_CONTEXT h2) => !(h1 == h2); - - /// Implements the operator ==. - /// The first handle. - /// The second handle. - /// The result of the operator. - public static bool operator ==(PACKAGEDEPENDENCY_CONTEXT h1, PACKAGEDEPENDENCY_CONTEXT h2) => h1.Equals(h2); - - /// - public override bool Equals(object obj) => obj is PACKAGEDEPENDENCY_CONTEXT h && handle == h.handle; - - /// - public override int GetHashCode() => handle.GetHashCode(); - - /// - public IntPtr DangerousGetHandle() => handle; + /// + /// Type: USHORT + /// The major version number of the package. + /// + public ushort Major; } } + + /// Provides a handle to a package dependency context. + [PInvokeData("appmodel.h")] + [StructLayout(LayoutKind.Sequential)] + public struct PACKAGEDEPENDENCY_CONTEXT : IHandle + { + private readonly IntPtr handle; + + /// Initializes a new instance of the struct. + /// An object that represents the pre-existing handle to use. + public PACKAGEDEPENDENCY_CONTEXT(IntPtr preexistingHandle) => handle = preexistingHandle; + + /// Returns an invalid handle by instantiating a object with . + public static PACKAGEDEPENDENCY_CONTEXT NULL => new(IntPtr.Zero); + + /// Gets a value indicating whether this instance is a null handle. + public bool IsNull => handle == IntPtr.Zero; + + /// Performs an explicit conversion from to . + /// The handle. + /// The result of the conversion. + public static explicit operator IntPtr(PACKAGEDEPENDENCY_CONTEXT h) => h.handle; + + /// Performs an implicit conversion from to . + /// The pointer to a handle. + /// The result of the conversion. + public static implicit operator PACKAGEDEPENDENCY_CONTEXT(IntPtr h) => new(h); + + /// Implements the operator !=. + /// The first handle. + /// The second handle. + /// The result of the operator. + public static bool operator !=(PACKAGEDEPENDENCY_CONTEXT h1, PACKAGEDEPENDENCY_CONTEXT h2) => !(h1 == h2); + + /// Implements the operator ==. + /// The first handle. + /// The second handle. + /// The result of the operator. + public static bool operator ==(PACKAGEDEPENDENCY_CONTEXT h1, PACKAGEDEPENDENCY_CONTEXT h2) => h1.Equals(h2); + + /// + public override bool Equals(object? obj) => obj is PACKAGEDEPENDENCY_CONTEXT h && handle == h.handle; + + /// + public override int GetHashCode() => handle.GetHashCode(); + + /// + public IntPtr DangerousGetHandle() => handle; + } } \ No newline at end of file diff --git a/PInvoke/Ole/Ole32/OCIdl.cs b/PInvoke/Ole/Ole32/OCIdl.cs index 8db5eea5..361ba9fb 100644 --- a/PInvoke/Ole/Ole32/OCIdl.cs +++ b/PInvoke/Ole/Ole32/OCIdl.cs @@ -8289,7 +8289,7 @@ namespace Vanara.PInvoke // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iviewobject-getcolorset HRESULT GetColorSet( DWORD // dwDrawAspect, LONG lindex, void *pvAspect, DVTARGETDEVICE *ptd, HDC hicTargetDev, LOGPALETTE **ppColorSet ); new unsafe HRESULT GetColorSet(DVASPECT dwDrawAspect, int lindex, [In, Optional] DVASPECTINFO* pvAspect, [In, Optional] DVTARGETDEVICE* ptd, - [In, Optional] HDC hicTargetDev, out LOGPALETTE ppColorSet); + [In, Optional] HDC hicTargetDev, [MarshalAs(UnmanagedType.CustomMarshaler, MarshalTypeRef = typeof(VanaraCustomMarshaler))] out LOGPALETTE ppColorSet); /// /// Freezes the drawn representation of an object so that it will not change until the IViewObject::Unfreeze method is called. diff --git a/PInvoke/Ole/Ole32/OleIdl.cs b/PInvoke/Ole/Ole32/OleIdl.cs index 55584150..1db223ef 100644 --- a/PInvoke/Ole/Ole32/OleIdl.cs +++ b/PInvoke/Ole/Ole32/OleIdl.cs @@ -2,6972 +2,6972 @@ using System.Runtime.CompilerServices; using System.Runtime.InteropServices; using System.Runtime.InteropServices.ComTypes; +using Vanara.InteropServices; -namespace Vanara.PInvoke +namespace Vanara.PInvoke; + +public static partial class Ole32 { - public static partial class Ole32 + /// Specifies what to do with caches that are to be discarded from memory if their dirty bit has been set. + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/ne-oleidl-discardcache typedef enum tagDISCARDCACHE { + // DISCARDCACHE_SAVEIFDIRTY, DISCARDCACHE_NOSAVE } DISCARDCACHE; + [PInvokeData("oleidl.h", MSDNShortId = "NE:oleidl.tagDISCARDCACHE")] + public enum DISCARDCACHE { - /// Specifies what to do with caches that are to be discarded from memory if their dirty bit has been set. - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/ne-oleidl-discardcache typedef enum tagDISCARDCACHE { - // DISCARDCACHE_SAVEIFDIRTY, DISCARDCACHE_NOSAVE } DISCARDCACHE; - [PInvokeData("oleidl.h", MSDNShortId = "NE:oleidl.tagDISCARDCACHE")] - public enum DISCARDCACHE - { - /// The cache is to be saved to disk. - DISCARDCACHE_SAVEIFDIRTY, + /// The cache is to be saved to disk. + DISCARDCACHE_SAVEIFDIRTY, - /// The cache can be discarded without saving it. - DISCARDCACHE_NOSAVE, - } + /// The cache can be discarded without saving it. + DISCARDCACHE_NOSAVE, + } + + /// + /// + /// Represents information about the effects of a drag-and-drop operation. The DoDragDrop function and many of the methods in + /// the IDropSource and IDropTarget use the values of this enumeration. + /// + /// + /// + /// + /// Your application should always mask values from the DROPEFFECT enumeration to ensure compatibility with future + /// implementations. Presently, only some of the positions in a DROPEFFECT value have meaning. In the future, more + /// interpretations for the bits will be added. Drag sources and drop targets should carefully mask these values appropriately + /// before comparing. They should never compare a DROPEFFECT against, say, DROPEFFECT_COPY by doing the following: + /// + /// Instead, the application should always mask for the value or values being sought as using one of the following techniques: + /// This allows for the definition of new drop effects, while preserving backward compatibility with existing code. + /// + // https://docs.microsoft.com/en-us/windows/desktop/com/dropeffect-constants + [PInvokeData("OleIdl.h", MSDNShortId = "d8e46899-3fbf-4012-8dd3-67fa627526d5")] + [Flags] + // public static extern + public enum DROPEFFECT : uint + { + /// Drop target cannot accept the data. + DROPEFFECT_NONE = 0, + + /// Drop results in a copy. The original data is untouched by the drag source. + DROPEFFECT_COPY = 1, + + /// Drag source should remove the data. + DROPEFFECT_MOVE = 2, + + /// Drag source should create a link to the original data. + DROPEFFECT_LINK = 4, /// + /// Scrolling is about to start or is currently occurring in the target. This value is used in addition to the other values. + /// + DROPEFFECT_SCROLL = 0x80000000, + } + + /// Indicates whether an object should be saved before closing. + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/ne-oleidl-oleclose typedef enum tagOLECLOSE { OLECLOSE_SAVEIFDIRTY, + // OLECLOSE_NOSAVE, OLECLOSE_PROMPTSAVE } OLECLOSE; + [PInvokeData("oleidl.h", MSDNShortId = "386f24a4-11d7-4471-960e-1a3ff67ba3c5")] + public enum OLECLOSE + { + /// The object should be saved if it is dirty. + OLECLOSE_SAVEIFDIRTY, + + /// The object should not be saved, even if it is dirty. This flag is typically used when an object is being deleted. + OLECLOSE_NOSAVE, + + /// + /// If the object is dirty, the IOleObject::Close implementation should display a dialog box to let the end user determine + /// whether to save the object. However, if the object is in the running state but its user interface is invisible, the end user + /// should not be prompted, and the close should be handled as if OLECLOSE_SAVEIFDIRTY had been specified. + /// + OLECLOSE_PROMPTSAVE, + } + + /// Indicates the type of objects to be enumerated. + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/ne-oleidl-olecontf typedef enum tagOLECONTF { OLECONTF_EMBEDDINGS, + // OLECONTF_LINKS, OLECONTF_OTHERS, OLECONTF_ONLYUSER, OLECONTF_ONLYIFRUNNING } OLECONTF; + [PInvokeData("oleidl.h", MSDNShortId = "9c70fc86-7166-47dd-a424-741f18e381e3")] + public enum OLECONTF + { + /// Enumerates the embedded objects in the container. + OLECONTF_EMBEDDINGS = 1, + + /// Enumerates the linked objects in the container. + OLECONTF_LINKS, + + /// + /// Enumerates all objects in the container that are not OLE compound document objects (i.e., objects other than linked or + /// embedded objects). Use this flag to enumerate the container's pseudo-objects. + /// + OLECONTF_OTHERS, + + /// + /// Enumerates only those objects the user is aware of. For example, hidden named-ranges in Microsoft Excel would not be + /// enumerated using this value. + /// + OLECONTF_ONLYUSER, + + /// Enumerates only those linked or embedded objects that are currently in the running state for this container. + OLECONTF_ONLYIFRUNNING, + } + + /// Controls aspects of the behavior of the IOleObject::GetMoniker and IOleClientSite::GetMoniker methods. + /// + /// If the OLEGETMONIKER_FORCEASSIGN flag causes a container to create a moniker for the object, the container should notify the + /// object by calling the IOleObject::GetMoniker method. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/ne-oleidl-olegetmoniker typedef enum tagOLEGETMONIKER { + // OLEGETMONIKER_ONLYIFTHERE, OLEGETMONIKER_FORCEASSIGN, OLEGETMONIKER_UNASSIGN, OLEGETMONIKER_TEMPFORUSER } OLEGETMONIKER; + [PInvokeData("oleidl.h", MSDNShortId = "b69e3213-08c4-45f8-b1b3-4ca78e966251")] + public enum OLEGETMONIKER + { + /// + /// If a moniker for the object or container does not exist, IOleClientSite::GetMoniker should return E_FAIL and not assign a moniker. + /// + OLEGETMONIKER_ONLYIFTHERE = 1, + + /// If a moniker for the object or container does not exist, IOleClientSite::GetMoniker should create one. + OLEGETMONIKER_FORCEASSIGN, + + /// + /// IOleClientSite::GetMoniker can release the object's moniker (although it is not required to do so). This constant is not + /// valid in IOleObject::GetMoniker. + /// + OLEGETMONIKER_UNASSIGN, + + /// + /// If a moniker for the object does not exist, IOleObject::GetMoniker can create a temporary moniker that can be used for + /// display purposes (IMoniker::GetDisplayName) but not for binding. This enables the object server to return a descriptive name + /// for the object without incurring the overhead of creating and maintaining a moniker until a link is actually created. + /// + OLEGETMONIKER_TEMPFORUSER, + } + + /// Controls binding operations to a link source. + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/ne-oleidl-olelinkbind + // typedef enum tagOLELINKBIND { OLELINKBIND_EVENIFCLASSDIFF = 1 } OLELINKBIND; + [PInvokeData("oleidl.h", MSDNShortId = "NE:oleidl.tagOLELINKBIND")] + public enum OLELINKBIND + { + /// + /// Value: 1 /// - /// Represents information about the effects of a drag-and-drop operation. The DoDragDrop function and many of the methods in - /// the IDropSource and IDropTarget use the values of this enumeration. + /// The binding operation should proceed even if the current class of the link source is different from the last time the link + /// was bound. For example, the link source could be a Lotus spreadsheet that was converted to an Excel spreadsheet. /// /// - /// + OLELINKBIND_EVENIFCLASSDIFF = 1, + } + + /// + /// Describes miscellaneous characteristics of an object or class of objects. A container can call the IOleObject::GetMiscStatus + /// method to determine the OLEMISC bits set for an object. The values specified in an object server's CLSID\MiscStatus entry + /// in the registration database are based on the OLEMISC enumeration. These constants are also used in the dwStatus + /// member of the OBJECTDESCRIPTOR structure. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/ne-oleidl-olemisc typedef enum tagOLEMISC { OLEMISC_RECOMPOSEONRESIZE, + // OLEMISC_ONLYICONIC, OLEMISC_INSERTNOTREPLACE, OLEMISC_STATIC, OLEMISC_CANTLINKINSIDE, OLEMISC_CANLINKBYOLE1, + // OLEMISC_ISLINKOBJECT, OLEMISC_INSIDEOUT, OLEMISC_ACTIVATEWHENVISIBLE, OLEMISC_RENDERINGISDEVICEINDEPENDENT, + // OLEMISC_INVISIBLEATRUNTIME, OLEMISC_ALWAYSRUN, OLEMISC_ACTSLIKEBUTTON, OLEMISC_ACTSLIKELABEL, OLEMISC_NOUIACTIVATE, + // OLEMISC_ALIGNABLE, OLEMISC_SIMPLEFRAME, OLEMISC_SETCLIENTSITEFIRST, OLEMISC_IMEMODE, OLEMISC_IGNOREACTIVATEWHENVISIBLE, + // OLEMISC_WANTSTOMENUMERGE, OLEMISC_SUPPORTSMULTILEVELUNDO } OLEMISC; + [PInvokeData("oleidl.h", MSDNShortId = "0a90d126-fc28-460c-8eaf-cf98ae998f95")] + public enum OLEMISC + { + /// + /// When the container resizes the space allocated to displaying one of the object's presentations, the object wants to + /// recompose the presentation. This means that on resize, the object wants to do more than scale its picture. If this bit is + /// set, the container should force the object to the running state and call IOleObject::SetExtent with the new size. + /// + OLEMISC_RECOMPOSEONRESIZE, + + /// + /// The object has no useful content view other than its icon. From the user's perspective, the Display As Icon check box (in + /// the Paste Special dialog box) for this object should always be checked, and should not be uncheckable. Note that such an + /// object should still have a drawable content aspect; it will look the same as its icon view. + /// + OLEMISC_ONLYICONIC, + + /// + /// The object has initialized itself from the data in the container's current selection. Containers should examine this bit + /// after calling IOleObject::InitFromData to initialize an object from the current selection. If set, the container should + /// insert the object beside the current selection rather than replacing the current selection. If this bit is not set, the + /// object being inserted replaces the current selection. + /// + OLEMISC_INSERTNOTREPLACE, + + /// + /// This object is a static object, which is an object that contains only a presentation; it contains no native data. See OleCreateStaticFromData. + /// + OLEMISC_STATIC, + + /// + /// This object cannot be the link source that when bound to activates (runs) the object. If the object is selected and copied + /// to the clipboard, the object's container can offer a link in a clipboard data transfer that, when bound, must connect to the + /// outside of the object. The user would see the object selected in its container, not open for editing. Rather than doing + /// this, the container can simply refuse to offer a link source when transferring objects with this bit set. Examples of + /// objects that have this bit set include OLE1 objects, static objects, and links. + /// + OLEMISC_CANTLINKINSIDE, + + /// + /// This object can be linked to by OLE 1 containers. This bit is used in the dwStatus member of the OBJECTDESCRIPTOR structure + /// transferred with the Object and Link Source Descriptor formats. An object can be linked to by OLE 1 containers if it is an + /// untitled document, a file, or a selection of data within a file. Embedded objects or pseudo-objects that are contained + /// within an embedded object cannot be linked to by OLE 1 containers (i.e., OLE 1 containers cannot link to link sources that, + /// when bound, require more than one object server to be run. + /// + OLEMISC_CANLINKBYOLE1, + + /// + /// This object is a link object. This bit is significant to OLE 1 and is set by the OLE 2 link object; object applications have + /// no need to set this bit. + /// + OLEMISC_ISLINKOBJECT, + + /// + /// This object is capable of activating in-place, without requiring installation of menus and toolbars to run. Several such + /// objects can be active concurrently. Some containers, such as forms, may choose to activate such objects automatically. + /// + OLEMISC_INSIDEOUT, + + /// + /// This bit is set only when OLEMISC_INSIDEOUT is set, and indicates that this object prefers to be activated whenever it is + /// visible. Some containers may always ignore this hint. + /// + OLEMISC_ACTIVATEWHENVISIBLE, + + /// This object does not pay any attention to target devices. Its presention data will be the same in all cases. + OLEMISC_RENDERINGISDEVICEINDEPENDENT, + + /// + /// This value is used with controls. It indicates that the control has no run-time user interface, but that it should be + /// visible at design time. For example, a timer control that fires a specific event periodically would not show itself at run + /// time, but it needs a design-time user interface so a form designer can set the event period and other properties. + /// + OLEMISC_INVISIBLEATRUNTIME, + + /// + /// This value is used with controls. It tells the container that this control always wants to be running. As a result, the + /// container should call OleRun when loading or creating the object. + /// + OLEMISC_ALWAYSRUN, + + /// + /// This value is used with controls. It indicates that the control is buttonlike in that it understands and obeys the + /// container's DisplayAsDefault ambient property. + /// + OLEMISC_ACTSLIKEBUTTON, + + /// + /// This value is used with controls. It marks the control as a label for whatever control comes after it in the form's + /// ordering. Pressing a mnemonic key for a label control activates the control after it. + /// + OLEMISC_ACTSLIKELABEL, + + /// + /// This value is used with controls. It indicates that the control has no UI active state, meaning that it requires no in-place + /// tools, no shared menu, and no accelerators. It also means that the control never needs the focus. + /// + OLEMISC_NOUIACTIVATE, + + /// + /// This value is used with controls. It indicates that the control understands how to align itself within its display + /// rectangle, according to alignment properties such as left, center, and right. + /// + OLEMISC_ALIGNABLE, + + /// + /// This value is used with controls. It indicates that the control is a simple grouping of other controls and does little more + /// than pass Windows messages to the control container managing the form. Controls of this sort require the implementation of + /// ISimpleFrameSite on the container's site. + /// + OLEMISC_SIMPLEFRAME, + + /// + /// This value is used with controls. It indicates that the control wants to use IOleObject::SetClientSite as its initialization + /// function, even before a call such as IPersistStreamInit::InitNew or IPersistStorage::InitNew. This allows the control to + /// access a container's ambient properties before loading information from persistent storage. Note that the current + /// implementations of OleCreate, OleCreateFromData, OleCreateFromFile, OleLoad, and the default handler do not understand this + /// value. Control containers that wish to honor this value must currently implement their own versions of these functions in + /// order to establish the correct initialization sequence for the control. + /// + OLEMISC_SETCLIENTSITEFIRST, + + /// + /// Obsolete. A control that works with an Input Method Editor (IME) system component can control the state of the IME through + /// the IMEMode property rather than using this value in the OLEMISC enumeration. You can use an IME component to enter + /// information in Asian character sets with a regular keyboard. A Japanese IME, for example, allows you to type a word such as + /// "sushi," on a regular keyboard and when you hit the spacebar, the IME component converts that word to appropriate kanji or + /// proposes possible choices. The OLEMISC_IMEMODE value was previously used to mark a control as capable of controlling an IME + /// mode system component. + /// + OLEMISC_IMEMODE, + + /// + /// For new ActiveX controls to work in an older container, the control may need to have the OLEMISC_ACTIVATEWHENVISIBLE value + /// set. However, in a newer container that understands and uses IPointerInactive, the control does not wish to be in-place + /// activated when it becomes visible. To allow the control to work in both kinds of containers, the control can set this value. + /// Then, the container ignores OLEMISC_ACTIVATEWHENVISIBLE and does not in-place activate the control when it becomes visible. + /// + OLEMISC_IGNOREACTIVATEWHENVISIBLE, + + /// A control that can merge its menu with its container sets this value. + OLEMISC_WANTSTOMENUMERGE, + + /// A control that supports multi-level undo sets this value. + OLEMISC_SUPPORTSMULTILEVELUNDO + } + + /// Indicates the type of caching requested for newly created objects. + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/ne-oleidl-olerender typedef enum tagOLERENDER { OLERENDER_NONE, + // OLERENDER_DRAW, OLERENDER_FORMAT, OLERENDER_ASIS } OLERENDER; + [PInvokeData("oleidl.h", MSDNShortId = "bab871ba-4ec4-49fd-854a-585732b91290")] + public enum OLERENDER + { + /// + /// The client is not requesting any locally cached drawing or data retrieval capabilities in the object. The pFormatEtc + /// parameter of the calls is ignored when this value is specified for the renderopts parameter. + /// + OLERENDER_NONE, + + /// + /// The client will draw the content of the object on the screen (a NULL target device) using IViewObject::Draw. The object + /// itself determines the data formats that need to be cached. With this render option, only the ptd and dwAspect members of + /// pFormatEtc are significant, since the object may cache things differently depending on the parameter values. However, + /// pFormatEtc can legally be NULL here, in which case the object is to assume the display target device and the + /// DVASPECT_CONTENT aspect. + /// + OLERENDER_DRAW, + + /// + /// The client will pull one format from the object using IDataObject::GetData. The format of the data to be cached is passed in + /// pFormatEtc, which may not in this case be NULL. + /// + OLERENDER_FORMAT, + + /// + /// The client is not requesting any locally cached drawing or data retrieval capabilities in the object. pFormatEtc is ignored + /// for this option. The difference between this and the OLERENDER_FORMAT value is important in such functions as + /// OleCreateFromData and OleCreateLinkFromData. + /// + OLERENDER_ASIS, + } + + /// + /// Indicates whether the linked object updates the cached data for the linked object automatically or only when the container calls + /// either the IOleObject::Update or IOleLink::Update methods. The constants are used in the IOleLink interface. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/ne-oleidl-oleupdate typedef enum tagOLEUPDATE { OLEUPDATE_ALWAYS = 1, + // OLEUPDATE_ONCALL = 3 } OLEUPDATE; + [PInvokeData("oleidl.h", MSDNShortId = "NE:oleidl.tagOLEUPDATE")] + public enum OLEUPDATE + { + /// + /// Value: 1 /// - /// Your application should always mask values from the DROPEFFECT enumeration to ensure compatibility with future - /// implementations. Presently, only some of the positions in a DROPEFFECT value have meaning. In the future, more - /// interpretations for the bits will be added. Drag sources and drop targets should carefully mask these values appropriately - /// before comparing. They should never compare a DROPEFFECT against, say, DROPEFFECT_COPY by doing the following: + /// Update the link object whenever possible, this option corresponds to the Automatic update option in the Links dialog box. /// - /// Instead, the application should always mask for the value or values being sought as using one of the following techniques: - /// This allows for the definition of new drop effects, while preserving backward compatibility with existing code. - /// - // https://docs.microsoft.com/en-us/windows/desktop/com/dropeffect-constants - [PInvokeData("OleIdl.h", MSDNShortId = "d8e46899-3fbf-4012-8dd3-67fa627526d5")] - [Flags] - // public static extern - public enum DROPEFFECT : uint - { - /// Drop target cannot accept the data. - DROPEFFECT_NONE = 0, - - /// Drop results in a copy. The original data is untouched by the drag source. - DROPEFFECT_COPY = 1, - - /// Drag source should remove the data. - DROPEFFECT_MOVE = 2, - - /// Drag source should create a link to the original data. - DROPEFFECT_LINK = 4, - - /// - /// Scrolling is about to start or is currently occurring in the target. This value is used in addition to the other values. - /// - DROPEFFECT_SCROLL = 0x80000000, - } - - /// Indicates whether an object should be saved before closing. - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/ne-oleidl-oleclose typedef enum tagOLECLOSE { OLECLOSE_SAVEIFDIRTY, - // OLECLOSE_NOSAVE, OLECLOSE_PROMPTSAVE } OLECLOSE; - [PInvokeData("oleidl.h", MSDNShortId = "386f24a4-11d7-4471-960e-1a3ff67ba3c5")] - public enum OLECLOSE - { - /// The object should be saved if it is dirty. - OLECLOSE_SAVEIFDIRTY, - - /// The object should not be saved, even if it is dirty. This flag is typically used when an object is being deleted. - OLECLOSE_NOSAVE, - - /// - /// If the object is dirty, the IOleObject::Close implementation should display a dialog box to let the end user determine - /// whether to save the object. However, if the object is in the running state but its user interface is invisible, the end user - /// should not be prompted, and the close should be handled as if OLECLOSE_SAVEIFDIRTY had been specified. - /// - OLECLOSE_PROMPTSAVE, - } - - /// Indicates the type of objects to be enumerated. - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/ne-oleidl-olecontf typedef enum tagOLECONTF { OLECONTF_EMBEDDINGS, - // OLECONTF_LINKS, OLECONTF_OTHERS, OLECONTF_ONLYUSER, OLECONTF_ONLYIFRUNNING } OLECONTF; - [PInvokeData("oleidl.h", MSDNShortId = "9c70fc86-7166-47dd-a424-741f18e381e3")] - public enum OLECONTF - { - /// Enumerates the embedded objects in the container. - OLECONTF_EMBEDDINGS = 1, - - /// Enumerates the linked objects in the container. - OLECONTF_LINKS, - - /// - /// Enumerates all objects in the container that are not OLE compound document objects (i.e., objects other than linked or - /// embedded objects). Use this flag to enumerate the container's pseudo-objects. - /// - OLECONTF_OTHERS, - - /// - /// Enumerates only those objects the user is aware of. For example, hidden named-ranges in Microsoft Excel would not be - /// enumerated using this value. - /// - OLECONTF_ONLYUSER, - - /// Enumerates only those linked or embedded objects that are currently in the running state for this container. - OLECONTF_ONLYIFRUNNING, - } - - /// Controls aspects of the behavior of the IOleObject::GetMoniker and IOleClientSite::GetMoniker methods. - /// - /// If the OLEGETMONIKER_FORCEASSIGN flag causes a container to create a moniker for the object, the container should notify the - /// object by calling the IOleObject::GetMoniker method. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/ne-oleidl-olegetmoniker typedef enum tagOLEGETMONIKER { - // OLEGETMONIKER_ONLYIFTHERE, OLEGETMONIKER_FORCEASSIGN, OLEGETMONIKER_UNASSIGN, OLEGETMONIKER_TEMPFORUSER } OLEGETMONIKER; - [PInvokeData("oleidl.h", MSDNShortId = "b69e3213-08c4-45f8-b1b3-4ca78e966251")] - public enum OLEGETMONIKER - { - /// - /// If a moniker for the object or container does not exist, IOleClientSite::GetMoniker should return E_FAIL and not assign a moniker. - /// - OLEGETMONIKER_ONLYIFTHERE = 1, - - /// If a moniker for the object or container does not exist, IOleClientSite::GetMoniker should create one. - OLEGETMONIKER_FORCEASSIGN, - - /// - /// IOleClientSite::GetMoniker can release the object's moniker (although it is not required to do so). This constant is not - /// valid in IOleObject::GetMoniker. - /// - OLEGETMONIKER_UNASSIGN, - - /// - /// If a moniker for the object does not exist, IOleObject::GetMoniker can create a temporary moniker that can be used for - /// display purposes (IMoniker::GetDisplayName) but not for binding. This enables the object server to return a descriptive name - /// for the object without incurring the overhead of creating and maintaining a moniker until a link is actually created. - /// - OLEGETMONIKER_TEMPFORUSER, - } - - /// Controls binding operations to a link source. - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/ne-oleidl-olelinkbind - // typedef enum tagOLELINKBIND { OLELINKBIND_EVENIFCLASSDIFF = 1 } OLELINKBIND; - [PInvokeData("oleidl.h", MSDNShortId = "NE:oleidl.tagOLELINKBIND")] - public enum OLELINKBIND - { - /// - /// Value: 1 - /// - /// The binding operation should proceed even if the current class of the link source is different from the last time the link - /// was bound. For example, the link source could be a Lotus spreadsheet that was converted to an Excel spreadsheet. - /// - /// - OLELINKBIND_EVENIFCLASSDIFF = 1, - } + /// + OLEUPDATE_ALWAYS = 1, /// - /// Describes miscellaneous characteristics of an object or class of objects. A container can call the IOleObject::GetMiscStatus - /// method to determine the OLEMISC bits set for an object. The values specified in an object server's CLSID\MiscStatus entry - /// in the registration database are based on the OLEMISC enumeration. These constants are also used in the dwStatus - /// member of the OBJECTDESCRIPTOR structure. + /// Value: 3 + /// + /// Update the link object only when IOleObject::Update or IOleLink::Update is called, this option corresponds to the Manual + /// update option in the Links dialog box. + /// /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/ne-oleidl-olemisc typedef enum tagOLEMISC { OLEMISC_RECOMPOSEONRESIZE, - // OLEMISC_ONLYICONIC, OLEMISC_INSERTNOTREPLACE, OLEMISC_STATIC, OLEMISC_CANTLINKINSIDE, OLEMISC_CANLINKBYOLE1, - // OLEMISC_ISLINKOBJECT, OLEMISC_INSIDEOUT, OLEMISC_ACTIVATEWHENVISIBLE, OLEMISC_RENDERINGISDEVICEINDEPENDENT, - // OLEMISC_INVISIBLEATRUNTIME, OLEMISC_ALWAYSRUN, OLEMISC_ACTSLIKEBUTTON, OLEMISC_ACTSLIKELABEL, OLEMISC_NOUIACTIVATE, - // OLEMISC_ALIGNABLE, OLEMISC_SIMPLEFRAME, OLEMISC_SETCLIENTSITEFIRST, OLEMISC_IMEMODE, OLEMISC_IGNOREACTIVATEWHENVISIBLE, - // OLEMISC_WANTSTOMENUMERGE, OLEMISC_SUPPORTSMULTILEVELUNDO } OLEMISC; - [PInvokeData("oleidl.h", MSDNShortId = "0a90d126-fc28-460c-8eaf-cf98ae998f95")] - public enum OLEMISC - { - /// - /// When the container resizes the space allocated to displaying one of the object's presentations, the object wants to - /// recompose the presentation. This means that on resize, the object wants to do more than scale its picture. If this bit is - /// set, the container should force the object to the running state and call IOleObject::SetExtent with the new size. - /// - OLEMISC_RECOMPOSEONRESIZE, + OLEUPDATE_ONCALL = 3, + } - /// - /// The object has no useful content view other than its icon. From the user's perspective, the Display As Icon check box (in - /// the Paste Special dialog box) for this object should always be checked, and should not be uncheckable. Note that such an - /// object should still have a drawable content aspect; it will look the same as its icon view. - /// - OLEMISC_ONLYICONIC, - - /// - /// The object has initialized itself from the data in the container's current selection. Containers should examine this bit - /// after calling IOleObject::InitFromData to initialize an object from the current selection. If set, the container should - /// insert the object beside the current selection rather than replacing the current selection. If this bit is not set, the - /// object being inserted replaces the current selection. - /// - OLEMISC_INSERTNOTREPLACE, - - /// - /// This object is a static object, which is an object that contains only a presentation; it contains no native data. See OleCreateStaticFromData. - /// - OLEMISC_STATIC, - - /// - /// This object cannot be the link source that when bound to activates (runs) the object. If the object is selected and copied - /// to the clipboard, the object's container can offer a link in a clipboard data transfer that, when bound, must connect to the - /// outside of the object. The user would see the object selected in its container, not open for editing. Rather than doing - /// this, the container can simply refuse to offer a link source when transferring objects with this bit set. Examples of - /// objects that have this bit set include OLE1 objects, static objects, and links. - /// - OLEMISC_CANTLINKINSIDE, - - /// - /// This object can be linked to by OLE 1 containers. This bit is used in the dwStatus member of the OBJECTDESCRIPTOR structure - /// transferred with the Object and Link Source Descriptor formats. An object can be linked to by OLE 1 containers if it is an - /// untitled document, a file, or a selection of data within a file. Embedded objects or pseudo-objects that are contained - /// within an embedded object cannot be linked to by OLE 1 containers (i.e., OLE 1 containers cannot link to link sources that, - /// when bound, require more than one object server to be run. - /// - OLEMISC_CANLINKBYOLE1, - - /// - /// This object is a link object. This bit is significant to OLE 1 and is set by the OLE 2 link object; object applications have - /// no need to set this bit. - /// - OLEMISC_ISLINKOBJECT, - - /// - /// This object is capable of activating in-place, without requiring installation of menus and toolbars to run. Several such - /// objects can be active concurrently. Some containers, such as forms, may choose to activate such objects automatically. - /// - OLEMISC_INSIDEOUT, - - /// - /// This bit is set only when OLEMISC_INSIDEOUT is set, and indicates that this object prefers to be activated whenever it is - /// visible. Some containers may always ignore this hint. - /// - OLEMISC_ACTIVATEWHENVISIBLE, - - /// This object does not pay any attention to target devices. Its presention data will be the same in all cases. - OLEMISC_RENDERINGISDEVICEINDEPENDENT, - - /// - /// This value is used with controls. It indicates that the control has no run-time user interface, but that it should be - /// visible at design time. For example, a timer control that fires a specific event periodically would not show itself at run - /// time, but it needs a design-time user interface so a form designer can set the event period and other properties. - /// - OLEMISC_INVISIBLEATRUNTIME, - - /// - /// This value is used with controls. It tells the container that this control always wants to be running. As a result, the - /// container should call OleRun when loading or creating the object. - /// - OLEMISC_ALWAYSRUN, - - /// - /// This value is used with controls. It indicates that the control is buttonlike in that it understands and obeys the - /// container's DisplayAsDefault ambient property. - /// - OLEMISC_ACTSLIKEBUTTON, - - /// - /// This value is used with controls. It marks the control as a label for whatever control comes after it in the form's - /// ordering. Pressing a mnemonic key for a label control activates the control after it. - /// - OLEMISC_ACTSLIKELABEL, - - /// - /// This value is used with controls. It indicates that the control has no UI active state, meaning that it requires no in-place - /// tools, no shared menu, and no accelerators. It also means that the control never needs the focus. - /// - OLEMISC_NOUIACTIVATE, - - /// - /// This value is used with controls. It indicates that the control understands how to align itself within its display - /// rectangle, according to alignment properties such as left, center, and right. - /// - OLEMISC_ALIGNABLE, - - /// - /// This value is used with controls. It indicates that the control is a simple grouping of other controls and does little more - /// than pass Windows messages to the control container managing the form. Controls of this sort require the implementation of - /// ISimpleFrameSite on the container's site. - /// - OLEMISC_SIMPLEFRAME, - - /// - /// This value is used with controls. It indicates that the control wants to use IOleObject::SetClientSite as its initialization - /// function, even before a call such as IPersistStreamInit::InitNew or IPersistStorage::InitNew. This allows the control to - /// access a container's ambient properties before loading information from persistent storage. Note that the current - /// implementations of OleCreate, OleCreateFromData, OleCreateFromFile, OleLoad, and the default handler do not understand this - /// value. Control containers that wish to honor this value must currently implement their own versions of these functions in - /// order to establish the correct initialization sequence for the control. - /// - OLEMISC_SETCLIENTSITEFIRST, - - /// - /// Obsolete. A control that works with an Input Method Editor (IME) system component can control the state of the IME through - /// the IMEMode property rather than using this value in the OLEMISC enumeration. You can use an IME component to enter - /// information in Asian character sets with a regular keyboard. A Japanese IME, for example, allows you to type a word such as - /// "sushi," on a regular keyboard and when you hit the spacebar, the IME component converts that word to appropriate kanji or - /// proposes possible choices. The OLEMISC_IMEMODE value was previously used to mark a control as capable of controlling an IME - /// mode system component. - /// - OLEMISC_IMEMODE, - - /// - /// For new ActiveX controls to work in an older container, the control may need to have the OLEMISC_ACTIVATEWHENVISIBLE value - /// set. However, in a newer container that understands and uses IPointerInactive, the control does not wish to be in-place - /// activated when it becomes visible. To allow the control to work in both kinds of containers, the control can set this value. - /// Then, the container ignores OLEMISC_ACTIVATEWHENVISIBLE and does not in-place activate the control when it becomes visible. - /// - OLEMISC_IGNOREACTIVATEWHENVISIBLE, - - /// A control that can merge its menu with its container sets this value. - OLEMISC_WANTSTOMENUMERGE, - - /// A control that supports multi-level undo sets this value. - OLEMISC_SUPPORTSMULTILEVELUNDO - } - - /// Indicates the type of caching requested for newly created objects. - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/ne-oleidl-olerender typedef enum tagOLERENDER { OLERENDER_NONE, - // OLERENDER_DRAW, OLERENDER_FORMAT, OLERENDER_ASIS } OLERENDER; - [PInvokeData("oleidl.h", MSDNShortId = "bab871ba-4ec4-49fd-854a-585732b91290")] - public enum OLERENDER - { - /// - /// The client is not requesting any locally cached drawing or data retrieval capabilities in the object. The pFormatEtc - /// parameter of the calls is ignored when this value is specified for the renderopts parameter. - /// - OLERENDER_NONE, - - /// - /// The client will draw the content of the object on the screen (a NULL target device) using IViewObject::Draw. The object - /// itself determines the data formats that need to be cached. With this render option, only the ptd and dwAspect members of - /// pFormatEtc are significant, since the object may cache things differently depending on the parameter values. However, - /// pFormatEtc can legally be NULL here, in which case the object is to assume the display target device and the - /// DVASPECT_CONTENT aspect. - /// - OLERENDER_DRAW, - - /// - /// The client will pull one format from the object using IDataObject::GetData. The format of the data to be cached is passed in - /// pFormatEtc, which may not in this case be NULL. - /// - OLERENDER_FORMAT, - - /// - /// The client is not requesting any locally cached drawing or data retrieval capabilities in the object. pFormatEtc is ignored - /// for this option. The difference between this and the OLERENDER_FORMAT value is important in such functions as - /// OleCreateFromData and OleCreateLinkFromData. - /// - OLERENDER_ASIS, - } + /// Describes the attributes of a specified verb for an object. + /// Values are used in the enumerator (which supports the IEnumOLEVERB interface) that is created by a call to IOleObject::EnumVerbs. + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/ne-oleidl-oleverbattrib typedef enum tagOLEVERBATTRIB { + // OLEVERBATTRIB_NEVERDIRTIES, OLEVERBATTRIB_ONCONTAINERMENU } OLEVERBATTRIB; + [PInvokeData("oleidl.h", MSDNShortId = "797498ba-5ad6-4476-87d8-de85b30396f4")] + [Flags] + public enum OLEVERBATTRIB + { + /// + /// Executing this verb will not cause the object to become dirty and is therefore in need of saving to persistent storage. + /// + OLEVERBATTRIB_NEVERDIRTIES = 1, /// - /// Indicates whether the linked object updates the cached data for the linked object automatically or only when the container calls - /// either the IOleObject::Update or IOleLink::Update methods. The constants are used in the IOleLink interface. + /// Indicates a verb that should appear in the container's menu of verbs for this object. OLEIVERB_HIDE, OLEIVERB_SHOW, and + /// OLEIVERB_OPEN never have this value set. /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/ne-oleidl-oleupdate typedef enum tagOLEUPDATE { OLEUPDATE_ALWAYS = 1, - // OLEUPDATE_ONCALL = 3 } OLEUPDATE; - [PInvokeData("oleidl.h", MSDNShortId = "NE:oleidl.tagOLEUPDATE")] - public enum OLEUPDATE - { - /// - /// Value: 1 - /// - /// Update the link object whenever possible, this option corresponds to the Automatic update option in the Links dialog box. - /// - /// - OLEUPDATE_ALWAYS = 1, + OLEVERBATTRIB_ONCONTAINERMENU = 2, + } - /// - /// Value: 3 - /// - /// Update the link object only when IOleObject::Update or IOleLink::Update is called, this option corresponds to the Manual - /// update option in the Links dialog box. - /// - /// - OLEUPDATE_ONCALL = 3, - } + /// Indicates which part of an object's moniker is being set or retrieved. + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/ne-oleidl-olewhichmk typedef enum tagOLEWHICHMK { OLEWHICHMK_CONTAINER, + // OLEWHICHMK_OBJREL, OLEWHICHMK_OBJFULL } OLEWHICHMK; + [PInvokeData("oleidl.h", MSDNShortId = "3774c868-c312-4e7c-aa57-cdb13000a87c")] + public enum OLEWHICHMK + { + /// + /// The moniker of the object's container. Typically, this is a file moniker. This moniker is not persistently stored inside the + /// object, since the container can be renamed even while the object is not loaded. + /// + OLEWHICHMK_CONTAINER = 1, - /// Describes the attributes of a specified verb for an object. - /// Values are used in the enumerator (which supports the IEnumOLEVERB interface) that is created by a call to IOleObject::EnumVerbs. - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/ne-oleidl-oleverbattrib typedef enum tagOLEVERBATTRIB { - // OLEVERBATTRIB_NEVERDIRTIES, OLEVERBATTRIB_ONCONTAINERMENU } OLEVERBATTRIB; - [PInvokeData("oleidl.h", MSDNShortId = "797498ba-5ad6-4476-87d8-de85b30396f4")] - [Flags] - public enum OLEVERBATTRIB - { - /// - /// Executing this verb will not cause the object to become dirty and is therefore in need of saving to persistent storage. - /// - OLEVERBATTRIB_NEVERDIRTIES = 1, + /// + /// The moniker of the object relative to its container. Typically, this is an item moniker, and it is part of the persistent + /// state of the object. If this moniker is composed on to the end of the container's moniker, the resulting moniker is the full + /// moniker of the object. + /// + OLEWHICHMK_OBJREL, - /// - /// Indicates a verb that should appear in the container's menu of verbs for this object. OLEIVERB_HIDE, OLEIVERB_SHOW, and - /// OLEIVERB_OPEN never have this value set. - /// - OLEVERBATTRIB_ONCONTAINERMENU = 2, - } + /// + /// The full moniker of the object. Binding to this moniker results in a connection to the object. This moniker is not + /// persistently stored inside the object, since the container can be renamed even while the object is not loaded. + /// + OLEWHICHMK_OBJFULL, + } - /// Indicates which part of an object's moniker is being set or retrieved. - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/ne-oleidl-olewhichmk typedef enum tagOLEWHICHMK { OLEWHICHMK_CONTAINER, - // OLEWHICHMK_OBJREL, OLEWHICHMK_OBJFULL } OLEWHICHMK; - [PInvokeData("oleidl.h", MSDNShortId = "3774c868-c312-4e7c-aa57-cdb13000a87c")] - public enum OLEWHICHMK - { - /// - /// The moniker of the object's container. Typically, this is a file moniker. This moniker is not persistently stored inside the - /// object, since the container can be renamed even while the object is not loaded. - /// - OLEWHICHMK_CONTAINER = 1, + /// The type of cache to be updated. + [Flags] + public enum UPDFCACHE : uint + { + /// Updates caches created by using ADVF_NODATA in the call to IOleCache::Cache. + UPDFCACHE_NODATACACHE = 0x00000001, - /// - /// The moniker of the object relative to its container. Typically, this is an item moniker, and it is part of the persistent - /// state of the object. If this moniker is composed on to the end of the container's moniker, the resulting moniker is the full - /// moniker of the object. - /// - OLEWHICHMK_OBJREL, + /// Updates caches created by using ADVFCACHE_ONSAVE in the call to IOleCache::Cache. + UPDFCACHE_ONSAVECACHE = 0x00000002, - /// - /// The full moniker of the object. Binding to this moniker results in a connection to the object. This moniker is not - /// persistently stored inside the object, since the container can be renamed even while the object is not loaded. - /// - OLEWHICHMK_OBJFULL, - } + /// Updates caches created by using ADVFCACHE_ONSTOP in the call to IOleCache::Cache. + UPDFCACHE_ONSTOPCACHE = 0x00000004, - /// The type of cache to be updated. - [Flags] - public enum UPDFCACHE : uint - { - /// Updates caches created by using ADVF_NODATA in the call to IOleCache::Cache. - UPDFCACHE_NODATACACHE = 0x00000001, + /// Dynamically updates the caches (as is normally done when the object sends out OnDataChange notices). + UPDFCACHE_NORMALCACHE = 0x00000008, - /// Updates caches created by using ADVFCACHE_ONSAVE in the call to IOleCache::Cache. - UPDFCACHE_ONSAVECACHE = 0x00000002, + /// Updates the cache if blank, regardless of any other flag specified. + UPDFCACHE_IFBLANK = 0x00000010, - /// Updates caches created by using ADVFCACHE_ONSTOP in the call to IOleCache::Cache. - UPDFCACHE_ONSTOPCACHE = 0x00000004, + /// Updates only caches that are blank. + UPDFCACHE_ONLYIFBLANK = 0x80000000, - /// Dynamically updates the caches (as is normally done when the object sends out OnDataChange notices). - UPDFCACHE_NORMALCACHE = 0x00000008, + /// The equivalent of using an OR operation to combine UPDFCACHE_IFBLANK and UPDFCACHE_ONSAVECACHE. + UPDFCACHE_IFBLANKORONSAVECACHE = (UPDFCACHE_IFBLANK | UPDFCACHE_ONSAVECACHE), - /// Updates the cache if blank, regardless of any other flag specified. - UPDFCACHE_IFBLANK = 0x00000010, + /// Updates all caches. + UPDFCACHE_ALL = ((uint)(~(UPDFCACHE_ONLYIFBLANK))), - /// Updates only caches that are blank. - UPDFCACHE_ONLYIFBLANK = 0x80000000, + /// + /// Updates all caches except those created with ADVF_NODATA in the call to IOleCache::Cache. Thus, you can control updates to + /// the caches created with the ADVF_NODATA flag and only update these caches explicitly. + /// + UPDFCACHE_ALLBUTNODATACACHE = (UPDFCACHE_ALL & ((uint)(~UPDFCACHE_NODATACACHE))) + } - /// The equivalent of using an OR operation to combine UPDFCACHE_IFBLANK and UPDFCACHE_ONSAVECACHE. - UPDFCACHE_IFBLANKORONSAVECACHE = (UPDFCACHE_IFBLANK | UPDFCACHE_ONSAVECACHE), + /// Indicates the different variants of the display name associated with a class of objects. + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/ne-oleidl-userclasstype typedef enum tagUSERCLASSTYPE { + // USERCLASSTYPE_FULL, USERCLASSTYPE_SHORT, USERCLASSTYPE_APPNAME } USERCLASSTYPE; + [PInvokeData("oleidl.h", MSDNShortId = "f35dd18a-7fde-4954-8315-bc9bfd933827")] + public enum USERCLASSTYPE + { + /// The full type name of the class. + USERCLASSTYPE_FULL = 1, - /// Updates all caches. - UPDFCACHE_ALL = ((uint)(~(UPDFCACHE_ONLYIFBLANK))), + /// A short name (maximum of 15 characters) that is used for popup menus and the Links dialog box. + USERCLASSTYPE_SHORT, - /// - /// Updates all caches except those created with ADVF_NODATA in the call to IOleCache::Cache. Thus, you can control updates to - /// the caches created with the ADVF_NODATA flag and only update these caches explicitly. - /// - UPDFCACHE_ALLBUTNODATACACHE = (UPDFCACHE_ALL & ((uint)(~UPDFCACHE_NODATACACHE))) - } - - /// Indicates the different variants of the display name associated with a class of objects. - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/ne-oleidl-userclasstype typedef enum tagUSERCLASSTYPE { - // USERCLASSTYPE_FULL, USERCLASSTYPE_SHORT, USERCLASSTYPE_APPNAME } USERCLASSTYPE; - [PInvokeData("oleidl.h", MSDNShortId = "f35dd18a-7fde-4954-8315-bc9bfd933827")] - public enum USERCLASSTYPE - { - /// The full type name of the class. - USERCLASSTYPE_FULL = 1, - - /// A short name (maximum of 15 characters) that is used for popup menus and the Links dialog box. - USERCLASSTYPE_SHORT, - - /// The name of the application servicing the class and is used in the result text in dialog boxes. - USERCLASSTYPE_APPNAME, - } + /// The name of the application servicing the class and is used in the result text in dialog boxes. + USERCLASSTYPE_APPNAME, + } + /// + /// + /// The IDropSource interface is one of the interfaces you implement to provide drag-and-drop operations in your application. + /// It contains methods used in any application used as a data source in a drag-and-drop operation. The data source application in a + /// drag-and-drop operation is responsible for: + /// + /// + /// + /// Determining the data being dragged based on the user's selection. + /// + /// + /// Initiating the drag-and-drop operation based on the user's mouse actions. + /// + /// + /// + /// Generating some of the visual feedback during the drag-and-drop operation, such as setting the cursor and highlighting the data + /// selected for the drag-and-drop operation. + /// + /// + /// + /// Canceling or completing the drag-and-drop operation based on the user's mouse actions. + /// + /// + /// Performing any action on the original data caused by the drop operation, such as deleting the data on a drag move. + /// + /// + /// + /// IDropSource contains the methods for generating visual feedback to the end user and for canceling or completing the + /// drag-and-drop operation. You also need to call the DoDragDrop, RegisterDragDrop, and RevokeDragDrop functions in drag-and-drop operations. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/oleidl/nn-oleidl-idropsource + [PInvokeData("oleidl.h", MSDNShortId = "963a36bc-4ad7-4591-bffc-a96b4310177d")] + [ComImport, Guid("00000121-0000-0000-C000-000000000046"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IDropSource + { /// /// - /// The IDropSource interface is one of the interfaces you implement to provide drag-and-drop operations in your application. - /// It contains methods used in any application used as a data source in a drag-and-drop operation. The data source application in a - /// drag-and-drop operation is responsible for: + /// Determines whether a drag-and-drop operation should be continued, canceled, or completed. You do not call this method + /// directly. The OLE DoDragDrop function calls this method during a drag-and-drop operation. /// - /// - /// - /// Determining the data being dragged based on the user's selection. - /// - /// - /// Initiating the drag-and-drop operation based on the user's mouse actions. - /// + /// + /// + /// + /// Indicates whether the Esc key has been pressed since the previous call to QueryContinueDrag or to DoDragDrop if this + /// is the first call to QueryContinueDrag. A TRUE value indicates the end user has pressed the escape key; a + /// FALSE value indicates it has not been pressed. + /// + /// + /// + /// + /// The current state of the keyboard modifier keys on the keyboard. Possible values can be a combination of any of the flags + /// MK_CONTROL, MK_SHIFT, MK_ALT, MK_BUTTON, MK_LBUTTON, MK_MBUTTON, and MK_RBUTTON. + /// + /// + /// + /// This method can return the following values. + /// + /// + /// Return code + /// Description + /// /// + /// S_OK /// - /// Generating some of the visual feedback during the drag-and-drop operation, such as setting the cursor and highlighting the data - /// selected for the drag-and-drop operation. + /// The drag operation should continue. This result occurs if no errors are detected, the mouse button starting the + /// drag-and-drop operation has not been released, and the Esc key has not been detected. /// /// /// - /// Canceling or completing the drag-and-drop operation based on the user's mouse actions. - /// - /// - /// Performing any action on the original data caused by the drop operation, such as deleting the data on a drag move. - /// - /// - /// - /// IDropSource contains the methods for generating visual feedback to the end user and for canceling or completing the - /// drag-and-drop operation. You also need to call the DoDragDrop, RegisterDragDrop, and RevokeDragDrop functions in drag-and-drop operations. - /// - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/oleidl/nn-oleidl-idropsource - [PInvokeData("oleidl.h", MSDNShortId = "963a36bc-4ad7-4591-bffc-a96b4310177d")] - [ComImport, Guid("00000121-0000-0000-C000-000000000046"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] - public interface IDropSource - { - /// - /// - /// Determines whether a drag-and-drop operation should be continued, canceled, or completed. You do not call this method - /// directly. The OLE DoDragDrop function calls this method during a drag-and-drop operation. - /// - /// - /// - /// - /// Indicates whether the Esc key has been pressed since the previous call to QueryContinueDrag or to DoDragDrop if this - /// is the first call to QueryContinueDrag. A TRUE value indicates the end user has pressed the escape key; a - /// FALSE value indicates it has not been pressed. - /// - /// - /// - /// - /// The current state of the keyboard modifier keys on the keyboard. Possible values can be a combination of any of the flags - /// MK_CONTROL, MK_SHIFT, MK_ALT, MK_BUTTON, MK_LBUTTON, MK_MBUTTON, and MK_RBUTTON. - /// - /// - /// - /// This method can return the following values. - /// - /// - /// Return code - /// Description - /// - /// - /// S_OK - /// - /// The drag operation should continue. This result occurs if no errors are detected, the mouse button starting the - /// drag-and-drop operation has not been released, and the Esc key has not been detected. - /// - /// - /// - /// DRAGDROP_S_DROP - /// - /// The drop operation should occur completing the drag operation. This result occurs if grfKeyState indicates that the key that - /// started the drag-and-drop operation has been released. - /// - /// - /// - /// DRAGDROP_S_CANCEL - /// - /// The drag operation should be canceled with no drop operation occurring. This result occurs if fEscapePressed is TRUE, - /// indicating the Esc key has been pressed. - /// - /// - /// - /// - /// - /// - /// The DoDragDrop function calls QueryContinueDrag whenever it detects a change in the keyboard or mouse button state - /// during a drag-and-drop operation. QueryContinueDrag must determine whether the drag-and-drop operation should be - /// continued, canceled, or completed based on the contents of the parameters grfKeyState and fEscapePressed. - /// - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/oleidl/nf-oleidl-idropsource-querycontinuedrag HRESULT - // QueryContinueDrag( BOOL fEscapePressed, DWORD grfKeyState ); - [PInvokeData("oleidl.h", MSDNShortId = "96ea44fc-5046-4e31-abfc-659d8ef3ca8f")] - [PreserveSig] - HRESULT QueryContinueDrag([MarshalAs(UnmanagedType.Bool)] bool fEscapePressed, uint grfKeyState); - - /// - /// - /// Enables a source application to give visual feedback to the end user during a drag-and-drop operation by providing the - /// DoDragDrop function with an enumeration value specifying the visual effect. - /// - /// - /// - /// The DROPEFFECT value returned by the most recent call to IDropTarget::DragEnter, IDropTarget::DragOver, or IDropTarget::DragLeave. - /// - /// - /// This method returns S_OK on success. Other possible values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// DRAGDROP_S_USEDEFAULTCURSORS - /// - /// Indicates successful completion of the method, and requests OLE to update the cursor using the OLE-provided default cursors. - /// - /// - /// - /// - /// - /// - /// When your application detects that the user has started a drag-and-drop operation, it should call the DoDragDrop function. - /// DoDragDrop enters a loop, calling IDropTarget::DragEnter when the mouse first enters a drop target window, - /// IDropTarget::DragOver when the mouse changes its position within the target window, and IDropTarget::DragLeave when the - /// mouse leaves the target window. - /// - /// - /// For every call to either IDropTarget::DragEnter or IDropTarget::DragOver, DoDragDrop calls IDropSource::GiveFeedback, - /// passing it the DROPEFFECT value returned from the drop target call. - /// - /// - /// DoDragDrop calls IDropTarget::DragLeave when the mouse has left the target window. Then, DoDragDrop calls - /// IDropSource::GiveFeedback and passes the DROPEFFECT_NONE value in the dwEffect parameter. - /// - /// - /// The dwEffect parameter can include DROPEFFECT_SCROLL, indicating that the source should put up the drag-scrolling variation - /// of the appropriate pointer. - /// - /// Notes to Implementers - /// - /// This function is called frequently during the DoDragDrop loop, so you can gain performance advantages if you optimize your - /// implementation as much as possible. - /// - /// - /// IDropSource::GiveFeedback is responsible for changing the cursor shape or for changing the highlighted source based - /// on the value of the dwEffect parameter. If you are using default cursors, you can return DRAGDROP_S_USEDEFAULTCURSORS, which - /// causes OLE to update the cursor for you, using its defaults. - /// - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/oleidl/nf-oleidl-idropsource-givefeedback HRESULT GiveFeedback( DWORD - // dwEffect ); - [PInvokeData("oleidl.h", MSDNShortId = "dde37299-ad7c-4f59-af99-e75b72ad9188")] - [PreserveSig] - HRESULT GiveFeedback(DROPEFFECT dwEffect); - } - - /// - /// The IDropSourceNotify interface is implemented on an IDropSource object to receive notifications from OLE when a user - /// drags the mouse into or out of a potential drop target window. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nn-oleidl-idropsourcenotify - [PInvokeData("oleidl.h", MSDNShortId = "NN:oleidl.IDropSourceNotify")] - [ComImport, Guid("0000012B-0000-0000-C000-000000000046"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] - public interface IDropSourceNotify - { - /// OLE calls this method when the user drags the mouse cursor into a potential drop target window. - /// The window handle of the potential drop target window. - /// This method returns S_OK on success. - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-idropsourcenotify-dragentertarget HRESULT - // DragEnterTarget( HWND hwndTarget ); - HRESULT DragEnterTarget([In] HWND hwndTarget); - - /// OLE calls this method when the user drags the mouse cursor out of a potential drop target window. - /// This method returns S_OK on success. - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-idropsourcenotify-dragleavetarget HRESULT DragLeaveTarget(); - HRESULT DragLeaveTarget(); - } - - /// - /// - /// The IDropTarget interface is one of the interfaces you implement to provide drag-and-drop operations in your application. - /// It contains methods used in any application that can be a target for data during a drag-and-drop operation. A drop-target - /// application is responsible for: - /// - /// - /// - /// Determining the effect of the drop on the target application. - /// - /// - /// Incorporating any valid dropped data when the drop occurs. - /// - /// + /// DRAGDROP_S_DROP /// - /// Communicating target feedback to the source so the source application can provide appropriate visual feedback such as setting - /// the cursor. + /// The drop operation should occur completing the drag operation. This result occurs if grfKeyState indicates that the key that + /// started the drag-and-drop operation has been released. /// /// /// - /// Implementing drag scrolling. + /// DRAGDROP_S_CANCEL + /// + /// The drag operation should be canceled with no drop operation occurring. This result occurs if fEscapePressed is TRUE, + /// indicating the Esc key has been pressed. + /// + /// + /// + /// + /// + /// + /// The DoDragDrop function calls QueryContinueDrag whenever it detects a change in the keyboard or mouse button state + /// during a drag-and-drop operation. QueryContinueDrag must determine whether the drag-and-drop operation should be + /// continued, canceled, or completed based on the contents of the parameters grfKeyState and fEscapePressed. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/oleidl/nf-oleidl-idropsource-querycontinuedrag HRESULT + // QueryContinueDrag( BOOL fEscapePressed, DWORD grfKeyState ); + [PInvokeData("oleidl.h", MSDNShortId = "96ea44fc-5046-4e31-abfc-659d8ef3ca8f")] + [PreserveSig] + HRESULT QueryContinueDrag([MarshalAs(UnmanagedType.Bool)] bool fEscapePressed, uint grfKeyState); + + /// + /// + /// Enables a source application to give visual feedback to the end user during a drag-and-drop operation by providing the + /// DoDragDrop function with an enumeration value specifying the visual effect. + /// + /// + /// + /// The DROPEFFECT value returned by the most recent call to IDropTarget::DragEnter, IDropTarget::DragOver, or IDropTarget::DragLeave. + /// + /// + /// This method returns S_OK on success. Other possible values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// DRAGDROP_S_USEDEFAULTCURSORS + /// + /// Indicates successful completion of the method, and requests OLE to update the cursor using the OLE-provided default cursors. + /// + /// + /// + /// + /// + /// + /// When your application detects that the user has started a drag-and-drop operation, it should call the DoDragDrop function. + /// DoDragDrop enters a loop, calling IDropTarget::DragEnter when the mouse first enters a drop target window, + /// IDropTarget::DragOver when the mouse changes its position within the target window, and IDropTarget::DragLeave when the + /// mouse leaves the target window. + /// + /// + /// For every call to either IDropTarget::DragEnter or IDropTarget::DragOver, DoDragDrop calls IDropSource::GiveFeedback, + /// passing it the DROPEFFECT value returned from the drop target call. + /// + /// + /// DoDragDrop calls IDropTarget::DragLeave when the mouse has left the target window. Then, DoDragDrop calls + /// IDropSource::GiveFeedback and passes the DROPEFFECT_NONE value in the dwEffect parameter. + /// + /// + /// The dwEffect parameter can include DROPEFFECT_SCROLL, indicating that the source should put up the drag-scrolling variation + /// of the appropriate pointer. + /// + /// Notes to Implementers + /// + /// This function is called frequently during the DoDragDrop loop, so you can gain performance advantages if you optimize your + /// implementation as much as possible. + /// + /// + /// IDropSource::GiveFeedback is responsible for changing the cursor shape or for changing the highlighted source based + /// on the value of the dwEffect parameter. If you are using default cursors, you can return DRAGDROP_S_USEDEFAULTCURSORS, which + /// causes OLE to update the cursor for you, using its defaults. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/oleidl/nf-oleidl-idropsource-givefeedback HRESULT GiveFeedback( DWORD + // dwEffect ); + [PInvokeData("oleidl.h", MSDNShortId = "dde37299-ad7c-4f59-af99-e75b72ad9188")] + [PreserveSig] + HRESULT GiveFeedback(DROPEFFECT dwEffect); + } + + /// + /// The IDropSourceNotify interface is implemented on an IDropSource object to receive notifications from OLE when a user + /// drags the mouse into or out of a potential drop target window. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nn-oleidl-idropsourcenotify + [PInvokeData("oleidl.h", MSDNShortId = "NN:oleidl.IDropSourceNotify")] + [ComImport, Guid("0000012B-0000-0000-C000-000000000046"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IDropSourceNotify + { + /// OLE calls this method when the user drags the mouse cursor into a potential drop target window. + /// The window handle of the potential drop target window. + /// This method returns S_OK on success. + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-idropsourcenotify-dragentertarget HRESULT + // DragEnterTarget( HWND hwndTarget ); + HRESULT DragEnterTarget([In] HWND hwndTarget); + + /// OLE calls this method when the user drags the mouse cursor out of a potential drop target window. + /// This method returns S_OK on success. + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-idropsourcenotify-dragleavetarget HRESULT DragLeaveTarget(); + HRESULT DragLeaveTarget(); + } + + /// + /// + /// The IDropTarget interface is one of the interfaces you implement to provide drag-and-drop operations in your application. + /// It contains methods used in any application that can be a target for data during a drag-and-drop operation. A drop-target + /// application is responsible for: + /// + /// + /// + /// Determining the effect of the drop on the target application. + /// + /// + /// Incorporating any valid dropped data when the drop occurs. + /// + /// + /// + /// Communicating target feedback to the source so the source application can provide appropriate visual feedback such as setting + /// the cursor. + /// + /// + /// + /// Implementing drag scrolling. + /// + /// + /// Registering and revoking its application windows as drop targets. + /// + /// + /// + /// The IDropTarget interface contains methods that handle all these responsibilities except registering and revoking the + /// application window as a drop target, for which you must call the RegisterDragDrop and the RevokeDragDrop functions. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/oleidl/nn-oleidl-idroptarget + [PInvokeData("oleidl.h", MSDNShortId = "13fbe834-1ef8-4944-b2e4-9f5c413c65c8")] + [ComImport, Guid("00000122-0000-0000-C000-000000000046"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IDropTarget + { + /// Indicates whether a drop can be accepted, and, if so, the effect of the drop. + /// + /// A pointer to the IDataObject interface on the data object. This data object contains the data being transferred in the + /// drag-and-drop operation. If the drop occurs, this data object will be incorporated into the target. + /// + /// + /// The current state of the keyboard modifier keys on the keyboard. Possible values can be a combination of any of the flags + /// MK_CONTROL, MK_SHIFT, MK_ALT, MK_BUTTON, MK_LBUTTON, MK_MBUTTON, and MK_RBUTTON. + /// + /// A POINTL structure containing the current cursor coordinates in screen coordinates. + /// + /// On input, pointer to the value of the pdwEffect parameter of the DoDragDrop function. On return, must contain one of the + /// DROPEFFECT flags, which indicates what the result of the drop operation would be. + /// + /// + /// This method returns S_OK on success. Other possible values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// E_UNEXPECTED + /// An unexpected error has occurred. /// /// - /// Registering and revoking its application windows as drop targets. + /// E_INVALIDARG + /// The pdwEffect parameter is NULL on input. + /// + /// + /// E_OUTOFMEMORY + /// There was insufficient memory available for this operation. + /// + /// + /// + /// + /// + /// You do not call DragEnter directly; instead the DoDragDrop function calls it to determine the effect of a drop the + /// first time the user drags the mouse into the registered window of a drop target. + /// + /// + /// To implement DragEnter, you must determine whether the target can use the data in the source data object by checking + /// three things: + /// + /// + /// + /// The format and medium specified by the data object + /// + /// + /// The input value of pdwEffect + /// + /// + /// The state of the modifier keys /// /// /// - /// The IDropTarget interface contains methods that handle all these responsibilities except registering and revoking the - /// application window as a drop target, for which you must call the RegisterDragDrop and the RevokeDragDrop functions. + /// To check the format and medium, use the IDataObject pointer passed in the pDataObject parameter to call + /// IDataObject::EnumFormatEtc so you can enumerate the FORMATETC structures the source data object supports. Then call + /// IDataObject::QueryGetData to determine whether the data object can render the data on the target by examining the formats + /// and medium specified for the data object. /// - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/oleidl/nn-oleidl-idroptarget - [PInvokeData("oleidl.h", MSDNShortId = "13fbe834-1ef8-4944-b2e4-9f5c413c65c8")] - [ComImport, Guid("00000122-0000-0000-C000-000000000046"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] - public interface IDropTarget - { - /// Indicates whether a drop can be accepted, and, if so, the effect of the drop. - /// - /// A pointer to the IDataObject interface on the data object. This data object contains the data being transferred in the - /// drag-and-drop operation. If the drop occurs, this data object will be incorporated into the target. - /// - /// - /// The current state of the keyboard modifier keys on the keyboard. Possible values can be a combination of any of the flags - /// MK_CONTROL, MK_SHIFT, MK_ALT, MK_BUTTON, MK_LBUTTON, MK_MBUTTON, and MK_RBUTTON. - /// - /// A POINTL structure containing the current cursor coordinates in screen coordinates. - /// - /// On input, pointer to the value of the pdwEffect parameter of the DoDragDrop function. On return, must contain one of the - /// DROPEFFECT flags, which indicates what the result of the drop operation would be. - /// - /// - /// This method returns S_OK on success. Other possible values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// E_UNEXPECTED - /// An unexpected error has occurred. - /// - /// - /// E_INVALIDARG - /// The pdwEffect parameter is NULL on input. - /// - /// - /// E_OUTOFMEMORY - /// There was insufficient memory available for this operation. - /// - /// - /// - /// - /// - /// You do not call DragEnter directly; instead the DoDragDrop function calls it to determine the effect of a drop the - /// first time the user drags the mouse into the registered window of a drop target. - /// - /// - /// To implement DragEnter, you must determine whether the target can use the data in the source data object by checking - /// three things: - /// - /// - /// - /// The format and medium specified by the data object - /// - /// - /// The input value of pdwEffect - /// - /// - /// The state of the modifier keys - /// - /// - /// - /// To check the format and medium, use the IDataObject pointer passed in the pDataObject parameter to call - /// IDataObject::EnumFormatEtc so you can enumerate the FORMATETC structures the source data object supports. Then call - /// IDataObject::QueryGetData to determine whether the data object can render the data on the target by examining the formats - /// and medium specified for the data object. - /// - /// - /// On entry to IDropTarget::DragEnter, the pdwEffect parameter is set to the effects given to the pdwOkEffect parameter - /// of the DoDragDrop function. The IDropTarget::DragEnter method must choose one of these effects or disable the drop. - /// - /// The following modifier keys affect the result of the drop. - /// - /// - /// Key Combination - /// User-Visible Feedback - /// Drop Effect - /// - /// - /// CTRL + SHIFT - /// = - /// DROPEFFECT_LINK - /// - /// - /// CTRL - /// + - /// DROPEFFECT_COPY - /// - /// - /// No keys or SHIFT - /// None - /// DROPEFFECT_MOVE - /// - /// - /// - /// On return, the method must write the effect, one of the DROPEFFECT flags, to the pdwEffect parameter. DoDragDrop then takes - /// this parameter and writes it to its pdwEffect parameter. You communicate the effect of the drop back to the source through - /// DoDragDrop in the pdwEffect parameter. The DoDragDrop function then calls IDropSource::GiveFeedback so that - /// the source application can display the appropriate visual feedback to the user through the target window. - /// - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/oleidl/nf-oleidl-idroptarget-dragenter HRESULT DragEnter( IDataObject - // *pDataObj, DWORD grfKeyState, POINTL pt, DWORD *pdwEffect ); - [PreserveSig] - HRESULT DragEnter([In] IDataObject pDataObj, [In] MouseButtonState grfKeyState, [In] POINT pt, [In, Out] ref DROPEFFECT pdwEffect); - - /// - /// Provides target feedback to the user and communicates the drop's effect to the DoDragDrop function so it can communicate the - /// effect of the drop back to the source. - /// - /// - /// The current state of the keyboard modifier keys on the keyboard. Valid values can be a combination of any of the flags - /// MK_CONTROL, MK_SHIFT, MK_ALT, MK_BUTTON, MK_LBUTTON, MK_MBUTTON, and MK_RBUTTON. - /// - /// A POINTL structure containing the current cursor coordinates in screen coordinates. - /// - /// On input, pointer to the value of the pdwEffect parameter of the DoDragDrop function. On return, must contain one of the - /// DROPEFFECT flags, which indicates what the result of the drop operation would be. - /// - /// - /// This method returns S_OK on success. Other possible values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// E_UNEXPECTED - /// An unexpected error has occurred. - /// - /// - /// E_INVALIDARG - /// The pdwEffect value is not valid. - /// - /// - /// E_OUTOFMEMORY - /// There was insufficient memory available for this operation. - /// - /// - /// - /// - /// - /// You do not call DragOver directly. The DoDragDrop function calls this method each time the user moves the mouse - /// across a given target window. DoDragDrop exits the loop if the drag-and-drop operation is canceled, if the user drags - /// the mouse out of the target window, or if the drop is completed. - /// - /// - /// In implementing IDropTarget::DragOver, you must provide features similar to those in IDropTarget::DragEnter. You must - /// determine the effect of dropping the data on the target by examining the FORMATETC defining the data object's formats and - /// medium, along with the state of the modifier keys. The mouse position may also play a role in determining the effect of a - /// drop. The following modifier keys affect the result of the drop. - /// - /// - /// - /// Key Combination - /// User-Visible Feedback - /// Drop Effect - /// - /// - /// CTRL + SHIFT - /// = - /// DROPEFFECT_LINK - /// - /// - /// CTRL - /// + - /// DROPEFFECT_COPY - /// - /// - /// No keys or SHIFT - /// None - /// DROPEFFECT_MOVE - /// - /// - /// - /// You communicate the effect of the drop back to the source through DoDragDrop in pdwEffect. The DoDragDrop function - /// then calls IDropSource::GiveFeedback so the source application can display the appropriate visual feedback to the user. - /// - /// - /// On entry to IDropTarget::DragOver, the pdwEffect parameter must be set to the allowed effects passed to the - /// pdwOkEffect parameter of the DoDragDrop function. The IDropTarget::DragOver method must be able to choose one of - /// these effects or disable the drop. - /// - /// - /// Upon return, pdwEffect is set to one of the DROPEFFECT flags. This value is then passed to the pdwEffect parameter of - /// DoDragDrop. Reasonable values are DROPEFFECT_COPY to copy the dragged data to the target, DROPEFFECT_LINK to create a link - /// to the source data, or DROPEFFECT_MOVE to allow the dragged data to be permanently moved from the source application to the target. - /// - /// - /// You may also wish to provide appropriate visual feedback in the target window. There may be some target feedback already - /// displayed from a previous call to IDropTarget::DragOver or from the initial IDropTarget::DragEnter. If this feedback - /// is no longer appropriate, you should remove it. - /// - /// - /// For efficiency reasons, a data object is not passed in IDropTarget::DragOver. The data object passed in the most - /// recent call to IDropTarget::DragEnter is available and can be used. - /// - /// - /// When IDropTarget::DragOver has completed its operation, the DoDragDrop function calls IDropSource::GiveFeedback so - /// the source application can display the appropriate visual feedback to the user. - /// - /// Notes to Implementers - /// - /// This function is called frequently during the DoDragDrop loop so it makes sense to optimize your implementation of the - /// DragOver method as much as possible. - /// - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/oleidl/nf-oleidl-idroptarget-dragover HRESULT DragOver( DWORD - // grfKeyState, POINTL pt, DWORD *pdwEffect ); - [PreserveSig] - HRESULT DragOver([In] MouseButtonState grfKeyState, [In] POINT pt, [In, Out] ref DROPEFFECT pdwEffect); - - /// Removes target feedback and releases the data object. - /// - /// This method returns S_OK on success. Other possible values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// E_OUTOFMEMORY - /// There is insufficient memory available for this operation. - /// - /// - /// - /// - /// You do not call this method directly. The DoDragDrop function calls this method in either of the following cases: - /// - /// - /// When the user drags the cursor out of a given target window. - /// - /// - /// When the user cancels the current drag-and-drop operation. - /// - /// - /// - /// To implement IDropTarget::DragLeave, you must remove any target feedback that is currently displayed. You must also - /// release any references you hold to the data transfer object. - /// - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/oleidl/nf-oleidl-idroptarget-dragleave HRESULT DragLeave( ); - [PreserveSig] - HRESULT DragLeave(); - - /// Incorporates the source data into the target window, removes target feedback, and releases the data object. - /// - /// A pointer to the IDataObject interface on the data object being transferred in the drag-and-drop operation. - /// - /// - /// The current state of the keyboard modifier keys on the keyboard. Possible values can be a combination of any of the flags - /// MK_CONTROL, MK_SHIFT, MK_ALT, MK_BUTTON, MK_LBUTTON, MK_MBUTTON, and MK_RBUTTON. - /// - /// A POINTL structure containing the current cursor coordinates in screen coordinates. - /// - /// On input, pointer to the value of the pdwEffect parameter of the DoDragDrop function. On return, must contain one of the - /// DROPEFFECT flags, which indicates what the result of the drop operation would be. - /// - /// - /// This method returns S_OK on success. Other possible values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// E_UNEXPECTED - /// An unexpected error has occurred. - /// - /// - /// E_INVALIDARG - /// The pdwEffect parameter is not valid. - /// - /// - /// E_OUTOFMEMORY - /// There is insufficient memory available for this operation. - /// - /// - /// - /// - /// - /// You do not call this method directly. The DoDragDrop function calls this method when the user completes the drag-and-drop operation. - /// - /// - /// In implementing Drop, you must incorporate the data object into the target. Use the formats available in IDataObject, - /// available through pDataObj, along with the current state of the modifier keys to determine how the data is to be - /// incorporated, such as linking or embedding. - /// - /// In addition to incorporating the data, you must also clean up as you do in the IDropTarget::DragLeave method: - /// - /// - /// Remove any target feedback that is currently displayed. - /// - /// - /// Release any references to the data object. - /// - /// - /// - /// You also pass the effect of this operation back to the source application through DoDragDrop, so the source application can - /// clean up after the drag-and-drop operation is complete: - /// - /// - /// - /// Remove any source feedback that is being displayed. - /// - /// - /// Make any necessary changes to the data, such as removing the data if the operation was a move. - /// - /// - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/oleidl/nf-oleidl-idroptarget-drop HRESULT Drop( IDataObject *pDataObj, - // DWORD grfKeyState, POINTL pt, DWORD *pdwEffect ); - [PreserveSig] - HRESULT Drop([In] IDataObject pDataObj, [In] MouseButtonState grfKeyState, [In] POINT pt, [In, Out] ref DROPEFFECT pdwEffect); - } + /// + /// On entry to IDropTarget::DragEnter, the pdwEffect parameter is set to the effects given to the pdwOkEffect parameter + /// of the DoDragDrop function. The IDropTarget::DragEnter method must choose one of these effects or disable the drop. + /// + /// The following modifier keys affect the result of the drop. + /// + /// + /// Key Combination + /// User-Visible Feedback + /// Drop Effect + /// + /// + /// CTRL + SHIFT + /// = + /// DROPEFFECT_LINK + /// + /// + /// CTRL + /// + + /// DROPEFFECT_COPY + /// + /// + /// No keys or SHIFT + /// None + /// DROPEFFECT_MOVE + /// + /// + /// + /// On return, the method must write the effect, one of the DROPEFFECT flags, to the pdwEffect parameter. DoDragDrop then takes + /// this parameter and writes it to its pdwEffect parameter. You communicate the effect of the drop back to the source through + /// DoDragDrop in the pdwEffect parameter. The DoDragDrop function then calls IDropSource::GiveFeedback so that + /// the source application can display the appropriate visual feedback to the user through the target window. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/oleidl/nf-oleidl-idroptarget-dragenter HRESULT DragEnter( IDataObject + // *pDataObj, DWORD grfKeyState, POINTL pt, DWORD *pdwEffect ); + [PreserveSig] + HRESULT DragEnter([In] IDataObject pDataObj, [In] MouseButtonState grfKeyState, [In] POINT pt, [In, Out] ref DROPEFFECT pdwEffect); /// - /// When implemented by the drop target application, this interface gives the OLE drag and drop engine the ability to determine - /// whether the drop target application intends to evaluate enterprise protection policy and gives the OLE drag and drop engine a - /// way to provide the enterprise ID of the drop source application to the drop target application. + /// Provides target feedback to the user and communicates the drop's effect to the DoDragDrop function so it can communicate the + /// effect of the drop back to the source. /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nn-oleidl-ienterprisedroptarget - [PInvokeData("oleidl.h", MSDNShortId = "NN:oleidl.IEnterpriseDropTarget")] - [ComImport, Guid("390E3878-FD55-4E18-819D-4682081C0CFD"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] - public interface IEnterpriseDropTarget - { - /// Provides the drop target with the enterprise ID of the drop source. - /// The enterprise identity of the drop source. - /// If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ienterprisedroptarget-setdropsourceenterpriseid HRESULT - // SetDropSourceEnterpriseId( LPCWSTR identity ); - HRESULT SetDropSourceEnterpriseId([MarshalAs(UnmanagedType.LPWStr)] string identity); + /// + /// The current state of the keyboard modifier keys on the keyboard. Valid values can be a combination of any of the flags + /// MK_CONTROL, MK_SHIFT, MK_ALT, MK_BUTTON, MK_LBUTTON, MK_MBUTTON, and MK_RBUTTON. + /// + /// A POINTL structure containing the current cursor coordinates in screen coordinates. + /// + /// On input, pointer to the value of the pdwEffect parameter of the DoDragDrop function. On return, must contain one of the + /// DROPEFFECT flags, which indicates what the result of the drop operation would be. + /// + /// + /// This method returns S_OK on success. Other possible values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// E_UNEXPECTED + /// An unexpected error has occurred. + /// + /// + /// E_INVALIDARG + /// The pdwEffect value is not valid. + /// + /// + /// E_OUTOFMEMORY + /// There was insufficient memory available for this operation. + /// + /// + /// + /// + /// + /// You do not call DragOver directly. The DoDragDrop function calls this method each time the user moves the mouse + /// across a given target window. DoDragDrop exits the loop if the drag-and-drop operation is canceled, if the user drags + /// the mouse out of the target window, or if the drop is completed. + /// + /// + /// In implementing IDropTarget::DragOver, you must provide features similar to those in IDropTarget::DragEnter. You must + /// determine the effect of dropping the data on the target by examining the FORMATETC defining the data object's formats and + /// medium, along with the state of the modifier keys. The mouse position may also play a role in determining the effect of a + /// drop. The following modifier keys affect the result of the drop. + /// + /// + /// + /// Key Combination + /// User-Visible Feedback + /// Drop Effect + /// + /// + /// CTRL + SHIFT + /// = + /// DROPEFFECT_LINK + /// + /// + /// CTRL + /// + + /// DROPEFFECT_COPY + /// + /// + /// No keys or SHIFT + /// None + /// DROPEFFECT_MOVE + /// + /// + /// + /// You communicate the effect of the drop back to the source through DoDragDrop in pdwEffect. The DoDragDrop function + /// then calls IDropSource::GiveFeedback so the source application can display the appropriate visual feedback to the user. + /// + /// + /// On entry to IDropTarget::DragOver, the pdwEffect parameter must be set to the allowed effects passed to the + /// pdwOkEffect parameter of the DoDragDrop function. The IDropTarget::DragOver method must be able to choose one of + /// these effects or disable the drop. + /// + /// + /// Upon return, pdwEffect is set to one of the DROPEFFECT flags. This value is then passed to the pdwEffect parameter of + /// DoDragDrop. Reasonable values are DROPEFFECT_COPY to copy the dragged data to the target, DROPEFFECT_LINK to create a link + /// to the source data, or DROPEFFECT_MOVE to allow the dragged data to be permanently moved from the source application to the target. + /// + /// + /// You may also wish to provide appropriate visual feedback in the target window. There may be some target feedback already + /// displayed from a previous call to IDropTarget::DragOver or from the initial IDropTarget::DragEnter. If this feedback + /// is no longer appropriate, you should remove it. + /// + /// + /// For efficiency reasons, a data object is not passed in IDropTarget::DragOver. The data object passed in the most + /// recent call to IDropTarget::DragEnter is available and can be used. + /// + /// + /// When IDropTarget::DragOver has completed its operation, the DoDragDrop function calls IDropSource::GiveFeedback so + /// the source application can display the appropriate visual feedback to the user. + /// + /// Notes to Implementers + /// + /// This function is called frequently during the DoDragDrop loop so it makes sense to optimize your implementation of the + /// DragOver method as much as possible. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/oleidl/nf-oleidl-idroptarget-dragover HRESULT DragOver( DWORD + // grfKeyState, POINTL pt, DWORD *pdwEffect ); + [PreserveSig] + HRESULT DragOver([In] MouseButtonState grfKeyState, [In] POINT pt, [In, Out] ref DROPEFFECT pdwEffect); - /// Indicates whether the drop target is intends to handle the evaluation of the enterprise protection policy. - /// - /// A boolean value that indicates whether the drop target intends to handle the evaluation of enterprise protection policy. - /// - /// If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ienterprisedroptarget-isevaluatingedppolicy HRESULT - // IsEvaluatingEdpPolicy( BOOL *value ); - HRESULT IsEvaluatingEdpPolicy([MarshalAs(UnmanagedType.Bool)] out bool value); - } + /// Removes target feedback and releases the data object. + /// + /// This method returns S_OK on success. Other possible values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// E_OUTOFMEMORY + /// There is insufficient memory available for this operation. + /// + /// + /// + /// + /// You do not call this method directly. The DoDragDrop function calls this method in either of the following cases: + /// + /// + /// When the user drags the cursor out of a given target window. + /// + /// + /// When the user cancels the current drag-and-drop operation. + /// + /// + /// + /// To implement IDropTarget::DragLeave, you must remove any target feedback that is currently displayed. You must also + /// release any references you hold to the data transfer object. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/oleidl/nf-oleidl-idroptarget-dragleave HRESULT DragLeave( ); + [PreserveSig] + HRESULT DragLeave(); + + /// Incorporates the source data into the target window, removes target feedback, and releases the data object. + /// + /// A pointer to the IDataObject interface on the data object being transferred in the drag-and-drop operation. + /// + /// + /// The current state of the keyboard modifier keys on the keyboard. Possible values can be a combination of any of the flags + /// MK_CONTROL, MK_SHIFT, MK_ALT, MK_BUTTON, MK_LBUTTON, MK_MBUTTON, and MK_RBUTTON. + /// + /// A POINTL structure containing the current cursor coordinates in screen coordinates. + /// + /// On input, pointer to the value of the pdwEffect parameter of the DoDragDrop function. On return, must contain one of the + /// DROPEFFECT flags, which indicates what the result of the drop operation would be. + /// + /// + /// This method returns S_OK on success. Other possible values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// E_UNEXPECTED + /// An unexpected error has occurred. + /// + /// + /// E_INVALIDARG + /// The pdwEffect parameter is not valid. + /// + /// + /// E_OUTOFMEMORY + /// There is insufficient memory available for this operation. + /// + /// + /// + /// + /// + /// You do not call this method directly. The DoDragDrop function calls this method when the user completes the drag-and-drop operation. + /// + /// + /// In implementing Drop, you must incorporate the data object into the target. Use the formats available in IDataObject, + /// available through pDataObj, along with the current state of the modifier keys to determine how the data is to be + /// incorporated, such as linking or embedding. + /// + /// In addition to incorporating the data, you must also clean up as you do in the IDropTarget::DragLeave method: + /// + /// + /// Remove any target feedback that is currently displayed. + /// + /// + /// Release any references to the data object. + /// + /// + /// + /// You also pass the effect of this operation back to the source application through DoDragDrop, so the source application can + /// clean up after the drag-and-drop operation is complete: + /// + /// + /// + /// Remove any source feedback that is being displayed. + /// + /// + /// Make any necessary changes to the data, such as removing the data if the operation was a move. + /// + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/oleidl/nf-oleidl-idroptarget-drop HRESULT Drop( IDataObject *pDataObj, + // DWORD grfKeyState, POINTL pt, DWORD *pdwEffect ); + [PreserveSig] + HRESULT Drop([In] IDataObject pDataObj, [In] MouseButtonState grfKeyState, [In] POINT pt, [In, Out] ref DROPEFFECT pdwEffect); + } + + /// + /// When implemented by the drop target application, this interface gives the OLE drag and drop engine the ability to determine + /// whether the drop target application intends to evaluate enterprise protection policy and gives the OLE drag and drop engine a + /// way to provide the enterprise ID of the drop source application to the drop target application. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nn-oleidl-ienterprisedroptarget + [PInvokeData("oleidl.h", MSDNShortId = "NN:oleidl.IEnterpriseDropTarget")] + [ComImport, Guid("390E3878-FD55-4E18-819D-4682081C0CFD"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IEnterpriseDropTarget + { + /// Provides the drop target with the enterprise ID of the drop source. + /// The enterprise identity of the drop source. + /// If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ienterprisedroptarget-setdropsourceenterpriseid HRESULT + // SetDropSourceEnterpriseId( LPCWSTR identity ); + HRESULT SetDropSourceEnterpriseId([MarshalAs(UnmanagedType.LPWStr)] string identity); + + /// Indicates whether the drop target is intends to handle the evaluation of the enterprise protection policy. + /// + /// A boolean value that indicates whether the drop target intends to handle the evaluation of enterprise protection policy. + /// + /// If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ienterprisedroptarget-isevaluatingedppolicy HRESULT + // IsEvaluatingEdpPolicy( BOOL *value ); + HRESULT IsEvaluatingEdpPolicy([MarshalAs(UnmanagedType.Bool)] out bool value); + } + + /// + /// Enumerates the different verbs available for an object in order of ascending verb number. An enumerator that implements the + /// IEnumOLEVERB interface is returned by IOleObject::EnumVerbs. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nn-oleidl-ienumoleverb + [PInvokeData("oleidl.h", MSDNShortId = "fc9b3474-6f56-4274-af7d-72e0920c0457")] + [ComImport, Guid("00000104-0000-0000-C000-000000000046"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IEnumOLEVERB : Vanara.Collections.ICOMEnum + { + /// Retrieves the specified number of items in the enumeration sequence. + /// + /// The number of items to be retrieved. If there are fewer than the requested number of items left in the sequence, this method + /// retrieves the remaining elements. + /// + /// + /// An array of enumerated items. + /// + /// The enumerator is responsible for allocating any memory, and the caller is responsible for freeing it.If celt is greater + /// than 1, the caller must also pass a non-NULL pointer passed to pceltFetched to know how many pointers to release. + /// + /// + /// + /// The number of items that were retrieved. This parameter is always less than or equal to the number of items requested. This + /// parameter can be NULL if celt is 1. + /// + /// If the method retrieves the number of items requested, the return value is S_OK. Otherwise, it is S_FALSE. + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ienumoleverb-next HRESULT Next( ULONG celt, LPOLEVERB + // rgelt, ULONG *pceltFetched ); + [PInvokeData("oleidl.h", MSDNShortId = "bb934017-9054-42b5-89d4-a24f12829503")] + [PreserveSig, MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime)] + HRESULT Next([In] uint celt, + [Out, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)] OLEVERB[] rgelt, + out uint pceltFetched); + + /// Skips over the specified number of items in the enumeration sequence. + /// The number of items to be skipped. + /// If the method skips the number of items requested, the return value is S_OK. Otherwise, it is S_FALSE. + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ienumoleverb-skip HRESULT Skip( ULONG celt ); + [PInvokeData("oleidl.h", MSDNShortId = "f949f993-1c4c-4d42-ba23-93330f0e9967")] + [PreserveSig, MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime)] + HRESULT Skip([In] uint celt); + + /// Resets the enumeration sequence to the beginning. + /// + /// There is no guarantee that the same set of objects will be enumerated after the reset operation has completed. A static + /// collection is reset to the beginning, but it can be too expensive for some collections, such as files in a directory, to + /// guarantee this condition. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ienumoleverb-reset HRESULT Reset( ); + [PInvokeData("oleidl.h", MSDNShortId = "612a364a-e7c2-4efd-b55c-1050891f5e22")] + [MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime)] + void Reset(); /// /// Enumerates the different verbs available for an object in order of ascending verb number. An enumerator that implements the /// IEnumOLEVERB interface is returned by IOleObject::EnumVerbs. /// + /// + /// A pointer to an IEnumOLEVERB pointer variable that receives the interface pointer to the enumeration object. If the method + /// is unsuccessful, the value of this output variable is undefined. + /// // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nn-oleidl-ienumoleverb [PInvokeData("oleidl.h", MSDNShortId = "fc9b3474-6f56-4274-af7d-72e0920c0457")] - [ComImport, Guid("00000104-0000-0000-C000-000000000046"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] - public interface IEnumOLEVERB : Vanara.Collections.ICOMEnum - { - /// Retrieves the specified number of items in the enumeration sequence. - /// - /// The number of items to be retrieved. If there are fewer than the requested number of items left in the sequence, this method - /// retrieves the remaining elements. - /// - /// - /// An array of enumerated items. - /// - /// The enumerator is responsible for allocating any memory, and the caller is responsible for freeing it.If celt is greater - /// than 1, the caller must also pass a non-NULL pointer passed to pceltFetched to know how many pointers to release. - /// - /// - /// - /// The number of items that were retrieved. This parameter is always less than or equal to the number of items requested. This - /// parameter can be NULL if celt is 1. - /// - /// If the method retrieves the number of items requested, the return value is S_OK. Otherwise, it is S_FALSE. - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ienumoleverb-next HRESULT Next( ULONG celt, LPOLEVERB - // rgelt, ULONG *pceltFetched ); - [PInvokeData("oleidl.h", MSDNShortId = "bb934017-9054-42b5-89d4-a24f12829503")] - [PreserveSig, MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime)] - HRESULT Next([In] uint celt, - [Out, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)] OLEVERB[] rgelt, - out uint pceltFetched); - - /// Skips over the specified number of items in the enumeration sequence. - /// The number of items to be skipped. - /// If the method skips the number of items requested, the return value is S_OK. Otherwise, it is S_FALSE. - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ienumoleverb-skip HRESULT Skip( ULONG celt ); - [PInvokeData("oleidl.h", MSDNShortId = "f949f993-1c4c-4d42-ba23-93330f0e9967")] - [PreserveSig, MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime)] - HRESULT Skip([In] uint celt); - - /// Resets the enumeration sequence to the beginning. - /// - /// There is no guarantee that the same set of objects will be enumerated after the reset operation has completed. A static - /// collection is reset to the beginning, but it can be too expensive for some collections, such as files in a directory, to - /// guarantee this condition. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ienumoleverb-reset HRESULT Reset( ); - [PInvokeData("oleidl.h", MSDNShortId = "612a364a-e7c2-4efd-b55c-1050891f5e22")] - [MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime)] - void Reset(); - - /// - /// Enumerates the different verbs available for an object in order of ascending verb number. An enumerator that implements the - /// IEnumOLEVERB interface is returned by IOleObject::EnumVerbs. - /// - /// - /// A pointer to an IEnumOLEVERB pointer variable that receives the interface pointer to the enumeration object. If the method - /// is unsuccessful, the value of this output variable is undefined. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nn-oleidl-ienumoleverb - [PInvokeData("oleidl.h", MSDNShortId = "fc9b3474-6f56-4274-af7d-72e0920c0457")] - [MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime)] - [return: MarshalAs(UnmanagedType.Interface)] - IEnumOLEVERB Clone(); - } + [MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime)] + [return: MarshalAs(UnmanagedType.Interface)] + IEnumOLEVERB Clone(); + } + /// + /// Manages advisory connections and compound document notifications in an object server. Its methods are intended to be used to + /// implement the advisory methods of IOleObject. IOleAdviseHolder is implemented on an advise holder object. Its methods + /// establish and delete advisory connections from the object managed by the server to the object's container, which must contain an + /// advise sink (support the IAdviseSink interface). The advise holder object must also keep track of which advise sinks are + /// interested in which notifications and pass along the notifications as appropriate. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nn-oleidl-ioleadviseholder + [PInvokeData("oleidl.h", MSDNShortId = "680afee7-2bee-4d54-ae0b-3e4e0deb622f")] + [ComImport, InterfaceType(ComInterfaceType.InterfaceIsIUnknown), Guid("00000111-0000-0000-C000-000000000046")] + public interface IOleAdviseHolder + { /// - /// Manages advisory connections and compound document notifications in an object server. Its methods are intended to be used to - /// implement the advisory methods of IOleObject. IOleAdviseHolder is implemented on an advise holder object. Its methods - /// establish and delete advisory connections from the object managed by the server to the object's container, which must contain an - /// advise sink (support the IAdviseSink interface). The advise holder object must also keep track of which advise sinks are - /// interested in which notifications and pass along the notifications as appropriate. + /// Establishes an advisory connection between an OLE object and the calling object's advise sink. Through that sink, the + /// calling object can receive notification when the OLE object is renamed, saved, or closed. /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nn-oleidl-ioleadviseholder - [PInvokeData("oleidl.h", MSDNShortId = "680afee7-2bee-4d54-ae0b-3e4e0deb622f")] - [ComImport, InterfaceType(ComInterfaceType.InterfaceIsIUnknown), Guid("00000111-0000-0000-C000-000000000046")] - public interface IOleAdviseHolder - { - /// - /// Establishes an advisory connection between an OLE object and the calling object's advise sink. Through that sink, the - /// calling object can receive notification when the OLE object is renamed, saved, or closed. - /// - /// A pointer to the IAdviseSink interface on the advisory sink that should be informed of changes. - /// - /// A pointer to a token that can be passed to the IOleAdviseHolder::Unadvise method to delete the advisory connection. The - /// calling object is responsible for calling both IUnknown::AddRef and IUnknown::Release on this pointer. - /// - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// E_INVALIDARG - /// The supplied IAdviseSink interface pointer is invalid. - /// - /// - /// - /// - /// - /// Containers, object handlers, and link objects all create advise sinks to receive notification of changes in - /// compound-document objects of interest, such as embedded or linked objects. OLE objects of interest to these objects must - /// implement the IOleObject interface, which includes several advisory methods, including IOleObject::Advise. A call to this - /// method must set up an advisory connection with any advise sink that calls it, and maintain each connection until it is - /// closed. It must be able to handle more than one advisory connection at a time. - /// - /// - /// IOleAdviseHolder::Advise is intended to be used to simplify the implementation of IOleObject::Advise. You can get a - /// pointer to the OLE implementation of IOleAdviseHolder by calling CreateOleAdviseHolder, and then, to implement - /// IOleObject::Advise, just delegate the call to IOleAdviseHolder::Advise. Other IOleAdviseHolder methods are - /// intended to implement other IOleObject advisory methods. - /// - /// - /// If the attempt to establish an advisory connection is successful, the object receiving the call returns a nonzero value - /// through pdwConnection. If the attempt fails, the object returns a zero. To delete an advisory connection, the object with - /// the advise sink passes this nonzero token back to the object by calling IOleAdviseHolder::Advise. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleadviseholder-advise HRESULT Advise( IAdviseSink - // *pAdvise, DWORD *pdwConnection ); - [PreserveSig] - HRESULT Advise([In] IAdviseSink pAdvise, out uint pdwConnection); - - /// Deletes a previously established advisory connection. - /// The value previously returned by IOleAdviseHolder::Advise in pdwConnection. - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// OLE_E_NOCONNECTION - /// The dwConnection parameter does not represent a valid advisory connection. - /// - /// - /// - /// - /// - /// IOleAdviseHolder::Unadvise is intended to be used to implement IOleObject::Unadvise to delete an advisory connection. - /// In general, you would use the OLE advise holder having obtained a pointer through a call to CreateOleAdviseHolder. - /// - /// - /// Typically, containers call this method at shutdown or when an object is deleted. In certain cases, containers could call - /// this method on objects that are running but not currently visible, as a way of reducing the overhead of maintaining multiple - /// advisory connections. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleadviseholder-unadvise HRESULT Unadvise( DWORD - // dwConnection ); - [PreserveSig] - HRESULT Unadvise(uint dwConnection); - - /// Creates an enumerator that can be used to enumerate the advisory connections currently established for an object. - /// - /// A pointer to an IEnumSTATDATA pointer variable that receives the interface pointer to the new enumerator. If this parameter - /// is NULL, there are presently no advisory connections on the object, or an error occurred. The advise holder is responsible - /// for incrementing the reference count on the IEnumSTATDATA pointer this method supplies. It is the caller's responsibility to - /// call IUnknown::Release when it is finished with the pointer. - /// - /// This method returns S_OK on success. - /// - /// - /// IOleAdviseHolder::EnumAdvise creates an enumerator that can be used to enumerate an object's established advisory - /// connections. The method supplies a pointer to the IEnumSTATDATA interface on this enumerator. Advisory connection - /// information for each connection is stored in the STATDATA structure, and the enumerator must be able to enumerate these structures. - /// - /// - /// For this method, the only relevant structure members are pAdvise and dwConnection. Other members contain data - /// advisory information. When you call the enumeration methods, and while an enumeration is in progress, the effect of - /// registering or revoking advisory connections on what is to be enumerated is undefined. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleadviseholder-enumadvise HRESULT EnumAdvise( - // IEnumSTATDATA **ppenumAdvise ); - [PreserveSig] - HRESULT EnumAdvised(out IEnumSTATDATA ppenumAdvise); - - /// - /// Sends notification to all advisory sinks currently registered with the advise holder that the name of object has changed. - /// - /// A pointer to the new full moniker of the object. - /// This method returns S_OK if advise sinks were sent IAdviseSink::OnRename notifications. - /// - /// SendOnRename calls IAdviseSink::OnRename to advise the calling object, which must have already established an - /// advisory connection, that the object has a new moniker. If you are using the OLE advise holder (having obtained a pointer - /// through a call to CreateOleAdviseHolder), you can call SendOnRename in the implementation of IOleObject::SetMoniker, - /// when you have determined that the operation is successful. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleadviseholder-sendonrename HRESULT SendOnRename( - // IMoniker *pmk ); - [PreserveSig] - HRESULT SendOnRename(IMoniker pmk); - - /// - /// Sends notification to all advisory sinks currently registered with the advise holder that the object has been saved. - /// - /// This method returns S_OK if advise sinks were sent IAdviseSink::OnSave notifications. - /// - /// - /// SendOnSave calls IAdviseSink::OnSave to advise the calling object (client), which must have already established an - /// advisory connection, that the object has been saved. If you are using the OLE advise holder (having obtained a pointer - /// through a call to CreateOleAdviseHolder), you can call SendOnSave whenever you save the object the advise holder is - /// associated with. - /// - /// - /// To take the object from the running state to the loaded state, the client calls IOleObject::Close. Within that - /// implementation, if the user wants to save the object to persistent storage, the object calls IOleClientSite::SaveObject, - /// followed by the call to SendOnSave. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleadviseholder-sendonsave HRESULT SendOnSave( ); - [PreserveSig] - HRESULT SendOnSave(); - - /// Sends notification to all advisory sinks currently registered with the advise holder that the object has closed. - /// - /// This method returns S_OK if advise sinks were notified of the close operation through a call to the IAdviseSink::OnClose method. - /// - /// - /// SendOnClose must call IAdviseSink::OnClose on all advise sinks that have a valid advisory connection with the object, - /// whenever the object goes from the running state to the loaded state. This occurs through a call to IOleObject::Close, so you - /// can call SendOnClose when you determine that a Close operation has been successful. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleadviseholder-sendonclose HRESULT SendOnClose( ); - [PreserveSig] - HRESULT SendOnClose(); - } - - /// - /// Provides control of the presentation data that gets cached inside of an object. Cached presentation data is available to the - /// container of the object even when the server application is not running or is unavailable. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nn-oleidl-iolecache - [PInvokeData("oleidl.h", MSDNShortId = "b5ef85d0-b54e-4831-87f1-ac6763179181")] - [ComImport, InterfaceType(ComInterfaceType.InterfaceIsIUnknown), Guid("0000011e-0000-0000-C000-000000000046")] - public interface IOleCache - { - /// Specifies the format and other data to be cached inside an embedded object. - /// - /// A pointer to a FORMATETC structure that specifies the format and other data to be cached. View caching is specified by - /// passing a zero clipboard format in pformatetc. - /// - /// - /// A group of flags that control the caching. Possible values come from the ADVF enumeration. When used in this context, for a - /// cache, these values have specific meanings, which are outlined in Remarks. Refer to the ADVF enumeration for a more - /// detailed description. - /// - /// - /// A variable that receives the identifier of this connection, which can later be used to turn caching off (by passing it to - /// IOleCache::Uncache). If this value is 0, the connection was not established. The OLE-provided implementation uses nonzero - /// numbers for connection identifiers. - /// - /// - /// - /// IOleCache::Cache can specify either data caching or view (presentation) caching. To specify data caching, a valid - /// data format must be passed in pformatetc. For view caching, the cache object itself decides on the format to cache, so a - /// caller would pass a zero data format in pformatetc as follows: - /// - /// - /// A custom object handler can choose not to store data in a given format. Instead, it can synthesize it on demand when requested. - /// - /// - /// The advf value specifies a member of the ADVF enumeration. When one of these values (or an OR'd combination of more than one - /// value) is used in this context, these values mean the following. - /// - /// - /// - /// ADVF Value - /// Description - /// - /// - /// ADVF_NODATA - /// - /// The cache is not to be updated by changes made to the running object. Instead, the container will update the cache by - /// explicitly calling IOleCache::SetData, IDataObject::SetData, or IOleCache2::UpdateCache. This flag is usually used when the - /// iconic aspect of an object is being cached. - /// - /// - /// - /// ADVF_ONLYONCE - /// - /// Update the cache one time only. After the update is complete, the advisory connection between the object and the cache is - /// disconnected. The source object for the advisory connection calls the Release method. - /// - /// - /// - /// ADVF_PRIMEFIRST - /// - /// The object is not to wait for the data or view to change before updating the cache. OR'd with ADVF_ONLYONCE, this parameter - /// provides an asynchronous IDataObject::GetData call. - /// - /// - /// - /// ADVFCACHE_NOHANDLER - /// Synonym for ADVFCACHE_FORCEBUILTIN. - /// - /// - /// ADVFCACHE_FORCEBUILTIN - /// - /// Used by DLL object applications and object handlers that draw their objects to cache presentation data to ensure that there - /// is a presentation in the cache. This ensures that the data can be retrieved even when the object or handler code is not available. - /// - /// - /// - /// ADVFCACHE_ONSAVE - /// - /// Updates the cached representation only when the object containing the cache is saved. The cache is also updated when the OLE - /// object changes from the running state back to the loaded state (because a subsequent save operation would require running - /// the object again). - /// - /// - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolecache-cache HRESULT Cache( FORMATETC *pformatetc, - // DWORD advf, DWORD *pdwConnection ); - uint Cache(in FORMATETC pformatetc, ADVF advf); - - /// Removes a cache connection created previously using IOleCache::Cache. - /// - /// The cache connection to be removed. This nonzero value was returned by IOleCache::Cache when the cache was originally established. - /// - /// - /// The IOleCache::Uncache method removes a cache connection that was created in a prior call to IOleCache::Cache. It - /// uses the dwConnection parameter that was returned by the prior call to IOleCache::Cache. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolecache-uncache HRESULT Uncache( DWORD dwConnection ); - void Uncache(uint dwConnection); - - /// Creates an enumerator that can be used to enumerate the current cache connections. - /// - /// A pointer to an IEnumSTATDATA pointer variable that receives the interface pointer to the new enumerator object. If this - /// parameter is NULL, there are no cache connections at this time. - /// - /// - /// The enumerator object returned by this method implements the IEnumSTATDATA interface. IEnumSTATDATA enumerates the - /// data stored in an array of STATDATA structures containing information about current cache connections. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolecache-enumcache - IEnumSTATDATA EnumCache(); - - /// Fills the cache as needed using the data provided by the specified data object. - /// A pointer to the IDataObject interface on the data object from which the cache is to be initialized. - /// - /// InitCache is usually used when creating an object from a drag-and-drop operation or from a clipboard paste operation. - /// It fills the cache as needed with presentation data from all the data formats provided by the data object provided on the - /// clipboard or in the drag-and-drop operation. Helper functions like OleCreateFromData or OleCreateLinkFromData call this - /// method when needed. If a container does not use these helper functions to create compound document objects, it can use - /// IOleCache::Cache to set up the cache entries which are then filled by InitCache. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolecache-initcache HRESULT InitCache( IDataObject - // *pDataObject ); - void InitCache(IDataObject pDataObject); - - /// Initializes the cache with data in a specified format and on a specified medium. - /// - /// A pointer to a FORMATETC structure that specifies the format of the presentation data being placed in the cache. - /// - /// - /// A pointer to a STGMEDIUM structure that specifies the storage medium that contains the presentation data. - /// - /// - /// Indicates the ownership of the storage medium after completion of the method. If fRelease is TRUE, the cache takes - /// ownership, freeing the medium when it is finished using it. When fRelease is FALSE, the caller retains ownership and - /// is responsible for freeing the medium. The cache can only use the storage medium for the duration of the call. - /// - /// - /// - /// IOleCache::SetData is usually called when an object is created from the clipboard or through a drag-and-drop - /// operation, and Embed Source data is used to create the object. - /// - /// - /// IOleCache::SetData and IOleCache::InitCache are very similar. There are two main differences. The first difference is - /// that while IOleCache::InitCache initializes the cache with the presentation format provided by the data object, - /// IOleCache::SetData initializes it with a single format. Second, the IOleCache::SetData method ignores the - /// ADVF_NODATA flag while IOleCache::InitCache obeys this flag. - /// - /// A container can use this method to maintain a single aspect of an object, such as the icon aspect of the object. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolecache-setdata HRESULT SetData( FORMATETC *pformatetc, - // STGMEDIUM *pmedium, BOOL fRelease ); - void SetData(in FORMATETC pformatetc, in STGMEDIUM pmedium, [MarshalAs(UnmanagedType.Bool)] bool fRelease); - } - - /// Enables object clients to selectively update each cache that was created with IOleCache::Cache. - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nn-oleidl-iolecache2 - [PInvokeData("oleidl.h", MSDNShortId = "NN:oleidl.IOleCache2")] - [ComImport, Guid("00000128-0000-0000-C000-000000000046"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] - public interface IOleCache2 : IOleCache - { - /// Specifies the format and other data to be cached inside an embedded object. - /// - /// A pointer to a FORMATETC structure that specifies the format and other data to be cached. View caching is specified by - /// passing a zero clipboard format in pformatetc. - /// - /// - /// A group of flags that control the caching. Possible values come from the ADVF enumeration. When used in this context, for a - /// cache, these values have specific meanings, which are outlined in Remarks. Refer to the ADVF enumeration for a more - /// detailed description. - /// - /// - /// A variable that receives the identifier of this connection, which can later be used to turn caching off (by passing it to - /// IOleCache::Uncache). If this value is 0, the connection was not established. The OLE-provided implementation uses nonzero - /// numbers for connection identifiers. - /// - /// - /// - /// IOleCache::Cache can specify either data caching or view (presentation) caching. To specify data caching, a valid - /// data format must be passed in pformatetc. For view caching, the cache object itself decides on the format to cache, so a - /// caller would pass a zero data format in pformatetc as follows: - /// - /// - /// A custom object handler can choose not to store data in a given format. Instead, it can synthesize it on demand when requested. - /// - /// - /// The advf value specifies a member of the ADVF enumeration. When one of these values (or an OR'd combination of more than one - /// value) is used in this context, these values mean the following. - /// - /// - /// - /// ADVF Value - /// Description - /// - /// - /// ADVF_NODATA - /// - /// The cache is not to be updated by changes made to the running object. Instead, the container will update the cache by - /// explicitly calling IOleCache::SetData, IDataObject::SetData, or IOleCache2::UpdateCache. This flag is usually used when the - /// iconic aspect of an object is being cached. - /// - /// - /// - /// ADVF_ONLYONCE - /// - /// Update the cache one time only. After the update is complete, the advisory connection between the object and the cache is - /// disconnected. The source object for the advisory connection calls the Release method. - /// - /// - /// - /// ADVF_PRIMEFIRST - /// - /// The object is not to wait for the data or view to change before updating the cache. OR'd with ADVF_ONLYONCE, this parameter - /// provides an asynchronous IDataObject::GetData call. - /// - /// - /// - /// ADVFCACHE_NOHANDLER - /// Synonym for ADVFCACHE_FORCEBUILTIN. - /// - /// - /// ADVFCACHE_FORCEBUILTIN - /// - /// Used by DLL object applications and object handlers that draw their objects to cache presentation data to ensure that there - /// is a presentation in the cache. This ensures that the data can be retrieved even when the object or handler code is not available. - /// - /// - /// - /// ADVFCACHE_ONSAVE - /// - /// Updates the cached representation only when the object containing the cache is saved. The cache is also updated when the OLE - /// object changes from the running state back to the loaded state (because a subsequent save operation would require running - /// the object again). - /// - /// - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolecache-cache HRESULT Cache( FORMATETC *pformatetc, - // DWORD advf, DWORD *pdwConnection ); - new uint Cache(in FORMATETC pformatetc, ADVF advf); - - /// Removes a cache connection created previously using IOleCache::Cache. - /// - /// The cache connection to be removed. This nonzero value was returned by IOleCache::Cache when the cache was originally established. - /// - /// - /// The IOleCache::Uncache method removes a cache connection that was created in a prior call to IOleCache::Cache. It - /// uses the dwConnection parameter that was returned by the prior call to IOleCache::Cache. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolecache-uncache HRESULT Uncache( DWORD dwConnection ); - new void Uncache(uint dwConnection); - - /// Creates an enumerator that can be used to enumerate the current cache connections. - /// - /// A pointer to an IEnumSTATDATA pointer variable that receives the interface pointer to the new enumerator object. If this - /// parameter is NULL, there are no cache connections at this time. - /// - /// - /// The enumerator object returned by this method implements the IEnumSTATDATA interface. IEnumSTATDATA enumerates the - /// data stored in an array of STATDATA structures containing information about current cache connections. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolecache-enumcache - new IEnumSTATDATA EnumCache(); - - /// Fills the cache as needed using the data provided by the specified data object. - /// A pointer to the IDataObject interface on the data object from which the cache is to be initialized. - /// - /// InitCache is usually used when creating an object from a drag-and-drop operation or from a clipboard paste operation. - /// It fills the cache as needed with presentation data from all the data formats provided by the data object provided on the - /// clipboard or in the drag-and-drop operation. Helper functions like OleCreateFromData or OleCreateLinkFromData call this - /// method when needed. If a container does not use these helper functions to create compound document objects, it can use - /// IOleCache::Cache to set up the cache entries which are then filled by InitCache. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolecache-initcache HRESULT InitCache( IDataObject - // *pDataObject ); - new void InitCache(IDataObject pDataObject); - - /// Initializes the cache with data in a specified format and on a specified medium. - /// - /// A pointer to a FORMATETC structure that specifies the format of the presentation data being placed in the cache. - /// - /// - /// A pointer to a STGMEDIUM structure that specifies the storage medium that contains the presentation data. - /// - /// - /// Indicates the ownership of the storage medium after completion of the method. If fRelease is TRUE, the cache takes - /// ownership, freeing the medium when it is finished using it. When fRelease is FALSE, the caller retains ownership and - /// is responsible for freeing the medium. The cache can only use the storage medium for the duration of the call. - /// - /// - /// - /// IOleCache::SetData is usually called when an object is created from the clipboard or through a drag-and-drop - /// operation, and Embed Source data is used to create the object. - /// - /// - /// IOleCache::SetData and IOleCache::InitCache are very similar. There are two main differences. The first difference is - /// that while IOleCache::InitCache initializes the cache with the presentation format provided by the data object, - /// IOleCache::SetData initializes it with a single format. Second, the IOleCache::SetData method ignores the - /// ADVF_NODATA flag while IOleCache::InitCache obeys this flag. - /// - /// A container can use this method to maintain a single aspect of an object, such as the icon aspect of the object. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolecache-setdata HRESULT SetData( FORMATETC *pformatetc, - // STGMEDIUM *pmedium, BOOL fRelease ); - new void SetData(in FORMATETC pformatetc, in STGMEDIUM pmedium, [MarshalAs(UnmanagedType.Bool)] bool fRelease); - - /// Updates the specified caches. This method is used when the application needs precise control over caching. - /// - /// A pointer to the IDataObject interface on the data object from which the cache is updated. Object handlers and in-process - /// servers typically pass a non- NULL value. A container application usually passes NULL, and the source is - /// obtained from the currently running object. - /// - /// - /// The type of cache to be updated. This parameter can be one or more of the following values. - /// - /// - /// Value - /// Meaning - /// - /// - /// UPDFCACHE_NODATACACHE - /// Updates caches created by using ADVF_NODATA in the call to IOleCache::Cache. - /// - /// - /// UPDFCACHE_ONSAVECACHE - /// Updates caches created by using ADVFCACHE_ONSAVE in the call to IOleCache::Cache. - /// - /// - /// UPDFCACHE_ONSTOPCACHE - /// Updates caches created by using ADVFCACHE_ONSTOP in the call to IOleCache::Cache. - /// - /// - /// UPDFCACHE_NORMALCACHE - /// Dynamically updates the caches (as is normally done when the object sends out OnDataChange notices). - /// - /// - /// UPDFCACHE_IFBLANK - /// Updates the cache if blank, regardless of any other flag specified. - /// - /// - /// UPDFCACHE_ONLYIFBLANK - /// Updates only caches that are blank. - /// - /// - /// UPDFCACHE_ IFBLANKORONSAVECACHE - /// The equivalent of using an OR operation to combine UPDFCACHE_IFBLANK and UPDFCACHE_ONSAVECACHE. - /// - /// - /// UPDFCACHE_ALL - /// Updates all caches. - /// - /// - /// UPDFCACHE_ ALLBUTNODATACACHE - /// - /// Updates all caches except those created with ADVF_NODATA in the call to IOleCache::Cache. Thus, you can control updates to - /// the caches created with the ADVF_NODATA flag and only update these caches explicitly. - /// - /// - /// - /// - /// This parameter is reserved and must be NULL. - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// E_INVALIDARG - /// One of the arguments is not valid. - /// - /// - /// E_UNEXPECTED - /// An unexpected error has occurred. - /// - /// - /// E_OUTOFMEMORY - /// Insufficient memory is available for this operation. - /// - /// - /// OLE_E_NOTRUNNING - /// The specified pDataObject is not running. - /// - /// - /// CACHE_E_NOCACHE_UPDATED - /// None of the caches were updated. - /// - /// - /// CACHE_S_SOMECACHES_NOTUPDATED - /// Some of the caches were updated. - /// - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolecache2-updatecache HRESULT UpdateCache( LPDATAOBJECT - // pDataObject, DWORD grfUpdf, LPVOID pReserved ); - HRESULT UpdateCache(IDataObject pDataObject, UPDFCACHE grfUpdf, [In, Optional] IntPtr pReserved); - - /// Discards the caches found in memory. - /// - /// - /// A value from the DISCARDCACHE enumeration that indicates whether data is to be saved prior to being discarded. Containers - /// that have drawn a large object and need to free up memory can specify DISCARDCACHE_SAVEIFDIRTY so that the newest - /// presentation is saved for the next time the object must be drawn. - /// - /// - /// Containers that have activated an embedded object, made some changes, and then called IOleObject::Close with OLECLOSE_NOSAVE - /// to roll back the changes can specify DISCARDCACHE_NOSAVE to ensure that the native and presentation data are not out of synchronization. - /// - /// - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// OLE_E_NOSTORAGE - /// There is no storage available for saving the data in the cache. - /// - /// - /// STG_E_MEDIUMFULL - /// The storage medium is full. - /// - /// - /// - /// - /// - /// The IOleCache2::DiscardCache method is commonly used to handle low memory conditions by freeing memory currently - /// being used by presentation caches. - /// - /// After it is discarded, a cache will satisfy subsequent IDataObject::GetData calls by reverting to disk-based data. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolecache2-discardcache HRESULT DiscardCache( DWORD - // dwDiscardOptions ); - HRESULT DiscardCache(DISCARDCACHE dwDiscardOptions); - } - - /// - /// Provides proper maintenance of caches. It maintains the caches by connecting the running object's IDataObject implementation to - /// the cache, allowing the cache to receive notifications from the running object. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nn-oleidl-iolecachecontrol - [PInvokeData("oleidl.h", MSDNShortId = "NN:oleidl.IOleCacheControl")] - [ComImport, Guid("00000129-0000-0000-C000-000000000046"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] - public interface IOleCacheControl - { - /// - /// Notifies the cache that the data source object has entered the running state so that the cache object can establish advise - /// sinks as needed. - /// - /// A pointer to the IDataObject interface on the object that is entering the running state. - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// E_INVALIDARG - /// One of the arguments is not valid. - /// - /// - /// E_UNEXPECTED - /// An unexpected error has occurred. - /// - /// - /// E_OUTOFMEMORY - /// Insufficient memory is available for this operation. - /// - /// - /// - /// - /// - /// When OnRun is called, the cache sets up advisory connections as necessary with the source data object so it can - /// receive notifications. The advisory connection created between the running object and the cache is destroyed when - /// IOleCacheControl::OnStop is called. - /// - /// - /// Some object handlers or in-process servers might use the cache passively, and not call OnRun. These applications must - /// call IOleCache2::UpdateCache, IOleCache::InitCache, or IOleCache::SetData to fill the cache when necessary to ensure that - /// the cache gets updated. - /// - /// - /// OnRun does not add a reference count on the pointer to IDataObject passed in pDataObject. Because it is the - /// responsibility of the caller of OleRun to ensure that the lifetime of the pDataObject pointer lasts until OnStop is called, - /// the caller must be holding a pointer to IDataObject on the data object of interest. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolecachecontrol-onrun HRESULT OnRun( LPDATAOBJECT - // pDataObject ); - HRESULT OnRun(IDataObject pDataObject); - - /// - /// Notifies the cache that it should terminate any existing advise sinks. No indication is given as to whether a connection - /// actually existed. - /// - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// E_UNEXPECTED - /// An unexpected error has occurred. - /// - /// - /// E_OUTOFMEMORY - /// Insufficient memory is available for this operation. - /// - /// - /// - /// The data advisory connection between the running object and the cache is destroyed as part of calling OnStop. - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolecachecontrol-onstop HRESULT OnStop(); - HRESULT OnStop(); - } - - /// - /// - /// Provides the primary means by which an embedded object obtains information about the location and extent of its display site, - /// its moniker, its user interface, and other resources provided by its container. An object server calls IOleClientSite to - /// request services from the container. A container must provide one instance of IOleClientSite for every compound-document - /// object it contains. - /// - /// Note This interface is not supported for use across machine boundaries. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nn-oleidl-ioleclientsite - [PInvokeData("oleidl.h", MSDNShortId = "dafee149-926a-4d08-a43d-5847682db645")] - [ComImport, Guid("00000118-0000-0000-C000-000000000046"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] - public interface IOleClientSite - { - /// - /// Saves the embedded object associated with the client site. This function is synchronous; by the time it returns, the save - /// will be completed. - /// - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// E_FAIL - /// The operation has failed. - /// - /// - /// - /// - /// - /// An embedded object calls SaveObject to ask its container to save it to persistent storage when an end user chooses - /// the File Update or Exit commands. The call is synchronous, meaning that by the time it returns, the save operation will be completed. - /// - /// - /// Calls to SaveObject occur in most implementations of IOleObject::Close. Normally, when a container tells an object to - /// close, the container passes a flag specifying whether the object should save itself before closing, prompt the user for - /// instructions, or close without saving itself. If an object is instructed to save itself, either by its container or an end - /// user, it calls SaveObject to ask the container application to save the object's contents before the object closes - /// itself. If a container instructs an object not to save itself, the object should not call SaveObject. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleclientsite-saveobject HRESULT SaveObject( ); - [PreserveSig] - HRESULT SaveObject(); - - /// - /// Retrieves a moniker for the object's client site. An object can force the assignment of its own or its container's moniker - /// by specifying a value for dwAssign. - /// - /// - /// Specifies whether to get a moniker only if one already exists, force assignment of a moniker, create a temporary moniker, or - /// remove a moniker that has been assigned. In practice, you will usually request that the container force assignment of the - /// moniker. Possible values are taken from the OLEGETMONIKER enumeration. - /// - /// - /// Specifies whether to return the container's moniker, the object's moniker relative to the container, or the object's full - /// moniker. In practice, you will usually request the object's full moniker. Possible values are taken from the OLEWHICHMK enumeration. - /// - /// - /// A pointer to an IMoniker pointer variable that receives the interface pointer to the moniker for the object's client site. - /// If an error occurs, the implementation must set ppmk to NULL. Each time a container receives a call to - /// IOleClientSite::GetMoniker, it must increase the reference count on the ppmk pointer it returns. It is the caller's - /// responsibility to call Release when it is finished with the pointer. - /// - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// E_NOTIMPL - /// This container cannot assign monikers to objects. This is the case with OLE 1 containers. - /// - /// - /// - /// - /// - /// Containers implement GetMoniker as a way of passing out monikers for their embedded objects to clients that need to - /// link to those objects. - /// - /// - /// When a link is made to an embedded object or to a pseudo-object within it (a range of cells in a spreadsheet, for example), - /// the object needs a moniker to construct the composite moniker indicating the source of the link. If the embedded object does - /// not already have a moniker, it can call GetMoniker to request one. - /// - /// - /// Every container that expects to contain links to embeddings should support GetMoniker to give out - /// OLEWHICHMK_CONTAINER, thus enabling link tracking when the link client and link source files move, but maintain the same - /// relative position. - /// - /// - /// An object must not persistently store its full moniker or its container's moniker, because these can change while the object - /// is not loaded. For example, either the container or the object could be renamed, in which event, storing the container's - /// moniker or the object's full moniker would make it impossible for a client to track a link to the object. - /// - /// - /// In some very specialized cases, an object may no longer need a moniker previously assigned to it and may wish to have it - /// removed as an optimization. In such cases, the object can call GetMoniker with OLEGETMONIKER_UNASSIGN to have the - /// moniker removed. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleclientsite-getmoniker HRESULT GetMoniker( DWORD - // dwAssign, DWORD dwWhichMoniker, IMoniker **ppmk ); - [PreserveSig] - HRESULT GetMoniker(OLEGETMONIKER dwAssign, OLEWHICHMK dwWhichMoniker, out IMoniker ppmk); - - /// Retrieves a pointer to the object's container. - /// - /// Address of IOleContainer pointer variable that receives the interface pointer to the container object. If an error occurs, - /// the implementation must set ppContainer to NULL. - /// - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// OLE_E_NOT_SUPPORTED - /// The client site is in an OLE 1 container. - /// - /// - /// E_NOINTERFACE - /// The container does not implement the IOleContainer interface. - /// - /// - /// - /// - /// - /// If a container supports links to its embedded objects, implementing GetContainer enables link clients to enumerate - /// the container's objects and recursively traverse a containment hierarchy. This method is optional but recommended for all - /// containers that expect to support links to their embedded objects. - /// - /// - /// Link clients can traverse a hierarchy of compound-document objects by recursively calling GetContainer to get a - /// pointer to the link source's container; followed by QueryInterface to get a pointer to the container's IOleObject interface - /// and, finally, IOleObject::GetClientSite to get the container's client site in its container. - /// - /// - /// Simple containers that do not support links to their embedded objects probably do not need to implement this method. - /// Instead, they can return E_NOINTERFACE and set ppContainer to NULL. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleclientsite-getcontainer HRESULT GetContainer( - // IOleContainer **ppContainer ); - [PreserveSig] - HRESULT GetContainer(out IOleContainer ppContainer); - - /// - /// Asks a container to display its object to the user. This method ensures that the container itself is visible and not minimized. - /// - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// OLE_E_NOT_SUPPORTED - /// Client site is in an OLE 1 container. - /// - /// - /// - /// - /// - /// After a link client binds to a link source, it commonly calls IOleObject::DoVerb on the link source, usually requesting the - /// source to perform some action requiring that it display itself to the user. As part of its implementation of - /// IOleObject::DoVerb, the link source can call ShowObject, which forces the client to show the link source as - /// best it can. If the link source's container is itself an embedded object, it will recursively invoke ShowObject on - /// its own container. - /// - /// - /// Having called the ShowObject method, a link source has no guarantee of being appropriately displayed because its - /// container may not be able to do so at the time of the call. The ShowObject method does not guarantee visibility, only - /// that the container will do the best it can. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleclientsite-showobject HRESULT ShowObject( ); - [PreserveSig] - HRESULT ShowObject(); - - /// - /// Notifies a container when an embedded object's window is about to become visible or invisible. This method does not apply to - /// an object that is activated in place and therefore has no window separate from that of its container. - /// - /// Indicates whether an object's window is open (TRUE) or closed (FALSE). - /// This method returns S_OK on success. - /// - /// An embedded object calls OnShowWindow to keep its container informed when the object is open in a window. This window - /// may or may not be currently visible to the end user. The container uses this information to shade the object's client site - /// when the object is displayed in a window, and to remove the shading when the object is not. A shaded object, having received - /// this notification, knows that it already has an open window and therefore can respond to being double-clicked by bringing - /// this window quickly to the top, instead of launching its application in order to obtain a new one. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleclientsite-onshowwindow HRESULT OnShowWindow( BOOL - // fShow ); - [PreserveSig] - HRESULT OnShowWindow([MarshalAs(UnmanagedType.Bool)] bool fShow); - - /// Asks a container to resize the display site for embedded objects. - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// E_NOTIMPL - /// Client site does not support requests for new layout. - /// - /// - /// - /// - /// This method can either increase or decrease the space. Currently, there is no standard mechanism by which a container can - /// negotiate how much room an object would like. When such a negotiation is defined, responding to this method will be optional - /// for containers. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleclientsite-requestnewobjectlayout HRESULT - // RequestNewObjectLayout( ); - [PreserveSig] - HRESULT RequestNewObjectLayout(); - } - - /// - /// Enumerates objects in a compound document or lock a container in the running state. Container and object applications both - /// implement this interface. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nn-oleidl-iolecontainer - [PInvokeData("oleidl.h", MSDNShortId = "98549309-8ac8-4391-92ab-8a62269ff579")] - [ComImport, Guid("0000011b-0000-0000-C000-000000000046"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] - public interface IOleContainer : IParseDisplayName - { - /// Parses the specified display name and creates a corresponding moniker. - /// A pointer to the bind context to be used in this binding operation. See IBindCtx. - /// The display name to be parsed. - /// - /// A pointer to a variable that receives the number of characters in the display name that correspond to the ppmkOut moniker. - /// - /// - /// A pointer to an IMoniker pointer variable that receives the interface pointer to the resulting moniker. If an error occurs, - /// the implementation sets *ppmkOut to NULL. If *ppmkOut is non- NULL, the implementation must call AddRef; it is - /// the caller's responsibility to call Release. - /// - /// - /// This method can return the standard return values E_OUTOFMEMORY and E_UNEXPECTED, as well as the following values. - /// - /// - /// Return code - /// Description - /// - /// - /// S_OK - /// The method completed successfully. - /// - /// - /// MK_E_SYNTAX - /// - /// There is a syntax error in the display name. Parsing failed because pszDisplayName could only be partially resolved into a - /// moniker. In this case, *pchEaten has the number of characters that were successfully parsed into a moniker prefix. The - /// parameter ppmkOut should be NULL. - /// - /// - /// - /// MK_E_NOOBJECT - /// The display name does not identify a component in this namespace. - /// - /// - /// E_INVALIDARG - /// One or more parameters are not valid. - /// - /// - /// - /// - /// - /// In general, the maximum prefix of pszDisplayName that is syntactically valid and that represents an object should be - /// consumed by this method and converted to a moniker. - /// - /// - /// Typically, this method is called by MkParseDisplayName or MkParseDisplayNameEx. In the initial step of the parsing - /// operation, these functions can retrieve the IParseDisplayName interface directly from an instance of a class identified with - /// either the "@ProgID" or "ProgID" notation. Subsequent parsing steps can query for the interface on an intermediate object. - /// - /// - /// The main loops of MkParseDisplayName and MkParseDisplayNameEx find the next moniker piece by calling the equivalent method - /// in the IMoniker interface, that is, IMoniker::ParseDisplayName, on the moniker that it currently holds. In this call to - /// IMoniker::ParseDisplayName, the MkParseDisplayName or MkParseDisplayNameEx function passes NULL - /// in the pmkToLeft parameter. If the moniker currently held is a generic composite, the call to - /// IMoniker::ParseDisplayName is forwarded by that composite onto its last piece, passing the prefix of the composite to - /// the left of the piece in pmkToLeft. - /// - /// - /// Some moniker classes will be able to handle this parsing internally to themselves because they are designed to designate - /// only certain kinds of objects. Others will need to bind to the object that they designate to accomplish the parsing process. - /// As is usual, these objects should not be released by IMoniker::ParseDisplayName but instead should be transferred to the - /// bind context via IBindCtx::RegisterObjectBound or IBindCtx::GetRunningObjectTable followed by IRunningObjectTable::Register - /// for release at a later time. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iparsedisplayname-parsedisplayname HRESULT - // ParseDisplayName( IBindCtx *pbc, LPOLESTR pszDisplayName, ULONG *pchEaten, IMoniker **ppmkOut ); - [PreserveSig] - new HRESULT ParseDisplayName(IBindCtx pbc, [MarshalAs(UnmanagedType.LPWStr)] string pszDisplayName, out uint pchEaten, out IMoniker ppmkOut); - - /// Enumerates the objects in the current container. - /// Specifies which objects in a container are to be enumerated, as defined in the enumeration OLECONTF. - /// - /// A pointer to an IEnumUnknown pointer variable that receives the interface pointer to the enumerator object. Each time a - /// container receives a successful call to EnumObjects, it must increase the reference count on the ppenum pointer the method - /// returns. It is the caller's responsibility to call IUnknown::Release when it is done with the pointer. If an error is - /// returned, the implementation must set ppenum to NULL. - /// - /// This method returns S_OK on success. - /// - /// A container should implement EnumObjects to enable programmatic clients to find out what objects it holds. This - /// method, however, is not called in standard linking scenarios. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolecontainer-enumobjects HRESULT EnumObjects( DWORD - // grfFlags, IEnumUnknown **ppenum ); - [PreserveSig] - HRESULT EnumObjects(OLECONTF grfFlags, out IEnumUnknown ppenum); - - /// Keeps the container for embedded objects running until explicitly released. - /// Indicates whether to lock ( TRUE) or unlock ( FALSE) a container. - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// E_FAIL - /// The operation failed. - /// - /// - /// E_OUTOFMEMORY - /// Insufficient memory available for the operation. - /// - /// - /// - /// - /// An embedded object calls LockContainer to keep its container running when the object has link clients that require an - /// update. If an end user selects File Close from the container's menu, however, the container ignores all outstanding - /// LockContainer locks and closes the document anyway. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolecontainer-lockcontainer HRESULT LockContainer( BOOL - // fLock ); - [PreserveSig] - HRESULT LockContainer([MarshalAs(UnmanagedType.Bool)] bool fLock); - } - - /// - /// Provides a direct channel of communication between an in-place object and the associated application's outer-most frame window - /// and the document window within the application that contains the embedded object. The communication involves the translation of - /// messages, the state of the frame window (activated or deactivated), and the state of the document window (activated or - /// deactivated). Also, it informs the object when it needs to resize its borders, and manages modeless dialog boxes. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nn-oleidl-ioleinplaceactiveobject - [PInvokeData("oleidl.h", MSDNShortId = "b077c256-1109-494c-95c2-2d33bccbe47b")] - [ComImport, Guid("00000117-0000-0000-C000-000000000046"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] - public interface IOleInPlaceActiveObject : IOleWindow - { - /// - /// Retrieves a handle to one of the windows participating in in-place activation (frame, document, parent, or in-place object window). - /// - /// A pointer to a variable that receives the window handle. - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// E_FAIL - /// The object is windowless. - /// - /// - /// E_OUTOFMEMORY - /// There is insufficient memory available for this operation. - /// - /// - /// E_UNEXPECTED - /// An unexpected error has occurred. - /// - /// - /// - /// - /// - /// Five types of windows comprise the windows hierarchy. When a object is active in place, it has access to some or all of - /// these windows. - /// - /// - /// - /// Window - /// Description - /// - /// - /// Frame - /// The outermost main window where the container application's main menu resides. - /// - /// - /// Document - /// The window that displays the compound document containing the embedded object to the user. - /// - /// - /// Pane - /// - /// The subwindow of the document window that contains the object's view. Applicable only for applications with split-pane windows. - /// - /// - /// - /// Parent - /// - /// The container window that contains that object's view. The object application installs its window as a child of this window. - /// - /// - /// - /// In-place - /// - /// The window containing the active in-place object. The object application creates this window and installs it as a child of - /// its hatch window, which is a child of the container's parent window. - /// - /// - /// - /// - /// Each type of window has a different role in the in-place activation architecture. However, it is not necessary to employ a - /// separate physical window for each type. Many container applications use the same window for their frame, document, pane, and - /// parent windows. - /// - /// - [PreserveSig] - new HRESULT GetWindow(out HWND phwnd); - - /// Determines whether context-sensitive help mode should be entered during an in-place activation session. - /// - /// if help mode should be entered; if it should be exited. - /// - /// - /// - /// This method returns S_OK if the help mode was entered or exited successfully, depending on the value passed in . Other possible return values include the following.
- /// - /// - /// - /// Return code - /// Description - /// - /// - /// E_INVALIDARG - /// The specified value is not valid. - /// - /// - /// E_OUTOFMEMORY - /// There is insufficient memory available for this operation. - /// - /// - /// E_UNEXPECTED - /// An unexpected error has occurred. - /// - /// - /// - /// - /// Applications can invoke context-sensitive help when the user: - /// - /// presses SHIFT+F1, then clicks a topic - /// presses F1 when a menu item is selected - /// - /// - /// When SHIFT+F1 is pressed, either the frame or active object can receive the keystrokes. If the container's frame receives - /// the keystrokes, it calls its containing document's IOleWindow::ContextSensitiveHelp method with set to . This propagates the help state to all of its in-place objects so they can - /// correctly handle the mouse click or WM_COMMAND. - /// - /// - /// If an active object receives the SHIFT+F1 keystrokes, it calls the container's IOleWindow::ContextSensitiveHelp method with - /// set to , which then recursively calls each of its in-place sites until - /// there are no more to be notified. The container then calls its document's or frame's IOleWindow::ContextSensitiveHelp method - /// with set to . - /// - /// When in context-sensitive help mode, an object that receives the mouse click can either: - /// - /// Ignore the click if it does not support context-sensitive help. - /// - /// Tell all the other objects to exit context-sensitive help mode with ContextSensitiveHelp set to FALSE and then provide help - /// for that context. - /// - /// - /// - /// An object in context-sensitive help mode that receives a WM_COMMAND should tell all the other in-place objects to exit - /// context-sensitive help mode and then provide help for the command. - /// - /// - /// If a container application is to support context-sensitive help on menu items, it must either provide its own message filter - /// so that it can intercept the F1 key or ask the OLE library to add a message filter by calling OleSetMenuDescriptor, passing - /// valid, non-NULL values for the lpFrame and lpActiveObj parameters. - /// - /// - [PreserveSig] - new HRESULT ContextSensitiveHelp([MarshalAs(UnmanagedType.Bool)] bool fEnterMode); - - /// - /// Processes menu accelerator-key messages from the container's message queue. This method should only be used for objects - /// created by a DLL object application. - /// - /// A pointer to an MSG structure for the message that might need to be translated. - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// S_FALSE - /// The message was not translated. - /// - /// - /// E_INVALIDARG - /// The specified parameter values are not valid. - /// - /// - /// E_OUTOFMEMORY - /// IThere is insufficient memory available for the operation. - /// - /// - /// E_UNEXPECTED - /// An unexpected error has occurred. - /// - /// - /// - /// - /// Notes to Callers - /// - /// Active in-place objects must always be given the first chance at translating accelerator keystrokes. You can provide this - /// opportunity by calling IOleInPlaceActiveObject::TranslateAccelerator from your container's message loop before doing - /// any other translation. You should apply your own translation only when this method returns S_FALSE. - /// - /// - /// If you call IOleInPlaceActiveObject::TranslateAccelerator for an object that is not created by a DLL object - /// application, the default object handler returns S_FALSE. - /// - /// Notes to Implementers - /// - /// An object created by an EXE object application gets keystrokes from its own message pump, so the container does not get - /// those messages. - /// - /// If you need to implement this method, you can do so by simply wrapping the call to the TranslateAccelerator function. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplaceactiveobject-translateaccelerator HRESULT - // TranslateAccelerator( LPMSG lpmsg ); - [PreserveSig] - HRESULT TranslateAccelerator(in MSG lpmsg); - - /// Notifies the object when the container's top-level frame window is activated or deactivated. - /// - /// The state of the container's top-level frame window. This parameter is TRUE if the window is activating and - /// FALSE if it is deactivating. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplaceactiveobject-onframewindowactivate HRESULT - // OnFrameWindowActivate( BOOL fActivate ); - void OnFrameWindowActivate([MarshalAs(UnmanagedType.Bool)] bool fActivate); - - /// Notifies the active in-place object when the container's document window is activated or deactivated. - /// - /// The state of the MDI child document window. If this parameter is TRUE, the window is in the act of activating; if it - /// is FALSE, it is in the act of deactivating. - /// - /// - /// Notes to Callers - /// - /// Call IOleInPlaceActiveObject::OnDocWindowActivate when the MDI child document window is activated or deactivated and - /// the object is currently the active object for the document. - /// - /// Notes to Implementers - /// - /// You should include code in this method that installs frame-level tools during object activation. These tools include the - /// shared composite menu and/or optional toolbars and frame adornments. You should then take focus. When deactivating, the - /// object should remove the frame-level tools. Note that if you do not call IOleInPlaceUIWindow::SetBorderSpace with - /// pborderwidths set to NULL, you can avoid having to renegotiate border space. - /// - /// - /// While executing IOleInPlaceActiveObject::OnDocWindowActivate, do not make calls to the PeekMessage or GetMessage - /// functions, or a dialog box. Doing so may cause the system to deadlock. There are further restrictions on which OLE interface - /// methods and functions can be called from within IOleInPlaceActiveObject::OnDocWindowActivate. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplaceactiveobject-ondocwindowactivate HRESULT - // OnDocWindowActivate( BOOL fActivate ); - void OnDocWindowActivate([MarshalAs(UnmanagedType.Bool)] bool fActivate); - - /// Alerts the object that it needs to resize its border space. - /// - /// A pointer to a RECT structure containing the new outer rectangle within which the object can request border space for its tools. - /// - /// - /// A pointer to an IOleInPlaceUIWindow interface pointer for the frame or document window object whose border has changed. - /// - /// - /// This parameter is TRUE if the frame window object is calling IOleInPlaceActiveObject::ResizeBorder; otherwise, - /// it is FALSE. - /// - /// - /// Notes to Callers - /// - /// IOleInPlaceActiveObject::ResizeBorder is called by the top-level container's document or frame window object when the - /// border space allocated to the object should change. Because the active in-place object is not informed about which window - /// has changed (the frame- or document-level window), IOleInPlaceActiveObject::ResizeBorder must be passed the pointer - /// to the window's IOleInPlaceUIWindow interface. - /// - /// Notes to Implemeters - /// - /// In most cases, resizing only requires that you grow, shrink, or scale your object's frame adornments. However, for more - /// complicated adornments, you may be required to renegotiate for border space with calls to - /// IOleInPlaceUIWindow::SetBorderSpace and IOleInPlaceUIWindow::SetBorderSpace. - /// - /// - /// Note While executing IOleInPlaceActiveObject::ResizeBorder, do not make calls to the PeekMessage or GetMessage - /// functions, or a dialog box. Doing so may cause the system to deadlock. There are further restrictions on which OLE interface - /// methods and functions can be called from within IOleInPlaceActiveObject::ResizeBorder. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplaceactiveobject-resizeborder HRESULT - // ResizeBorder( LPCRECT prcBorder, IOleInPlaceUIWindow *pUIWindow, BOOL fFrameWindow ); - void ResizeBorder(in RECT prcBorder, [In] IOleInPlaceUIWindow pUIWindow, [MarshalAs(UnmanagedType.Bool)] bool fFrameWindow); - - /// Enables or disables modeless dialog boxes when the container creates or destroys a modal dialog box. - /// Indicates whether to enable modeless dialog box windows ( TRUE) or disable them FALSE. - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplaceactiveobject-enablemodeless HRESULT - // EnableModeless( BOOL fEnable ); - void EnableModeless([MarshalAs(UnmanagedType.Bool)] bool fEnable); - } - - /// - /// Controls the container's top-level frame window. This control involves allowing the container to insert its menu group into the - /// composite menu, install the composite menu into the appropriate window frame, and remove the container's menu elements from the - /// composite menu. It sets and displays status text relevant to the in-place object. It also enables or disables the frame's - /// modeless dialog boxes, and translates accelerator keystrokes intended for the container's frame. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nn-oleidl-ioleinplaceframe - [PInvokeData("oleidl.h", MSDNShortId = "c530aff7-fd83-413d-8945-0c9d1bfb51ba")] - [ComImport, Guid("00000116-0000-0000-C000-000000000046"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] - public interface IOleInPlaceFrame : IOleInPlaceUIWindow - { - /// - /// Retrieves a handle to one of the windows participating in in-place activation (frame, document, parent, or in-place object window). - /// - /// A pointer to a variable that receives the window handle. - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// E_FAIL - /// The object is windowless. - /// - /// - /// E_OUTOFMEMORY - /// There is insufficient memory available for this operation. - /// - /// - /// E_UNEXPECTED - /// An unexpected error has occurred. - /// - /// - /// - /// - /// - /// Five types of windows comprise the windows hierarchy. When a object is active in place, it has access to some or all of - /// these windows. - /// - /// - /// - /// Window - /// Description - /// - /// - /// Frame - /// The outermost main window where the container application's main menu resides. - /// - /// - /// Document - /// The window that displays the compound document containing the embedded object to the user. - /// - /// - /// Pane - /// - /// The subwindow of the document window that contains the object's view. Applicable only for applications with split-pane windows. - /// - /// - /// - /// Parent - /// - /// The container window that contains that object's view. The object application installs its window as a child of this window. - /// - /// - /// - /// In-place - /// - /// The window containing the active in-place object. The object application creates this window and installs it as a child of - /// its hatch window, which is a child of the container's parent window. - /// - /// - /// - /// - /// Each type of window has a different role in the in-place activation architecture. However, it is not necessary to employ a - /// separate physical window for each type. Many container applications use the same window for their frame, document, pane, and - /// parent windows. - /// - /// - [PreserveSig] - new HRESULT GetWindow(out HWND phwnd); - - /// Determines whether context-sensitive help mode should be entered during an in-place activation session. - /// - /// if help mode should be entered; if it should be exited. - /// - /// - /// - /// This method returns S_OK if the help mode was entered or exited successfully, depending on the value passed in . Other possible return values include the following.
- /// - /// - /// - /// Return code - /// Description - /// - /// - /// E_INVALIDARG - /// The specified value is not valid. - /// - /// - /// E_OUTOFMEMORY - /// There is insufficient memory available for this operation. - /// - /// - /// E_UNEXPECTED - /// An unexpected error has occurred. - /// - /// - /// - /// - /// Applications can invoke context-sensitive help when the user: - /// - /// presses SHIFT+F1, then clicks a topic - /// presses F1 when a menu item is selected - /// - /// - /// When SHIFT+F1 is pressed, either the frame or active object can receive the keystrokes. If the container's frame receives - /// the keystrokes, it calls its containing document's IOleWindow::ContextSensitiveHelp method with set to . This propagates the help state to all of its in-place objects so they can - /// correctly handle the mouse click or WM_COMMAND. - /// - /// - /// If an active object receives the SHIFT+F1 keystrokes, it calls the container's IOleWindow::ContextSensitiveHelp method with - /// set to , which then recursively calls each of its in-place sites until - /// there are no more to be notified. The container then calls its document's or frame's IOleWindow::ContextSensitiveHelp method - /// with set to . - /// - /// When in context-sensitive help mode, an object that receives the mouse click can either: - /// - /// Ignore the click if it does not support context-sensitive help. - /// - /// Tell all the other objects to exit context-sensitive help mode with ContextSensitiveHelp set to FALSE and then provide help - /// for that context. - /// - /// - /// - /// An object in context-sensitive help mode that receives a WM_COMMAND should tell all the other in-place objects to exit - /// context-sensitive help mode and then provide help for the command. - /// - /// - /// If a container application is to support context-sensitive help on menu items, it must either provide its own message filter - /// so that it can intercept the F1 key or ask the OLE library to add a message filter by calling OleSetMenuDescriptor, passing - /// valid, non-NULL values for the lpFrame and lpActiveObj parameters. - /// - /// - [PreserveSig] - new HRESULT ContextSensitiveHelp([MarshalAs(UnmanagedType.Bool)] bool fEnterMode); - - /// Retrieves the outer rectange for toolbars and controls while the object is active in place. - /// - /// A pointer to a RECT structure where the outer rectangle is to be returned. The structure's coordinates are relative to the - /// window being represented by the interface. - /// - /// - /// Notes to Callers - /// - /// The IOleInPlaceUIWindow::GetBorder function, when called on a document or frame window object, returns the outer - /// rectangle (relative to the window) where the object can put toolbars or similar controls. - /// - /// - /// If the object is to install these tools, it should negotiate space for the tools within this rectangle using - /// IOleInPlaceUIWindow::RequestBorderSpace and then call IOleInPlaceUIWindow::SetBorderSpace to get this space allocated. - /// - /// - /// Note While executing IOleInPlaceUIWindow::GetBorder, do not make calls to the PeekMessage or GetMessage - /// functions, or a dialog box. Doing so may cause the system to deadlock. There are further restrictions on which OLE interface - /// methods and functions can be called from within GetBorder. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplaceuiwindow-getborder HRESULT GetBorder( LPRECT - // lprectBorder ); - new void GetBorder(out RECT lprectBorder); - - /// - /// Determines whether there is space available for tools to be installed around the object's window frame while the object is - /// active in place. - /// - /// - /// A pointer to a BORDERWIDTHS structure containing the requested widths (in pixels) needed on each side of the window for the tools. - /// - /// - /// Notes to Callers - /// - /// The active in-place object calls IOleInPlaceUIWindow::RequestBorderSpace to ask if tools can be installed inside the - /// window frame. These tools would be allocated between the rectangle returned by IOleInPlaceUIWindow::GetBorder and the - /// BORDERWIDTHS structure specified in the argument to this call. - /// - /// - /// The space for the tools is not actually allocated to the object until it calls IOleInPlaceUIWindow::SetBorderSpace, allowing - /// the object to negotiate for space (such as while dragging toolbars around), but deferring the moving of tools until the - /// action is completed. - /// - /// - /// The object can install these tools by passing the width in pixels that is to be used on each side. For example, if the - /// object required 10 pixels on the top, 0 pixels on the bottom, and 5 pixels on the left and right sides, it would pass the - /// following BORDERWIDTHS structure to IOleInPlaceUIWindow::RequestBorderSpace: - /// - /// - /// Note While executing IOleInPlaceUIWindow::RequestBorderSpace, do not make calls to the PeekMessage or - /// GetMessage functions, or a dialog box. Doing so may cause the system to deadlock. There are further restrictions on which - /// OLE interface methods and functions can be called from within IOleInPlaceUIWindow::RequestBorderSpace. - /// - /// Notes to Implementers - /// - /// If the amount of space an active object uses for its toolbars is irrelevant to the container, it can simply return NOERROR - /// as shown in the following IOleInPlaceUIWindow::RequestBorderSpace example. Containers should not unduly restrict the - /// display of tools by an active in-place object. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplaceuiwindow-requestborderspace HRESULT - // RequestBorderSpace( LPCBORDERWIDTHS pborderwidths ); - new void RequestBorderSpace(in RECT pborderwidths); - - /// Allocates space for the border requested in the call to IOleInPlaceUIWindow::RequestBorderSpace. - /// - /// Pointer to a BORDERWIDTHS structure containing the requested width of the tools, in pixels. It can be NULL, - /// indicating the object does not need any space. - /// - /// - /// The object must call IOleInPlaceUIWindow::SetBorderSpace. It can do any one of the following: - /// - /// - /// Use its own toolbars, requesting border space of a specific size. - /// - /// - /// - /// Use no toolbars, but force the container to remove its toolbars by passing a valid BORDERWIDTHS structure containing nothing - /// but zeros in the pborderwidths parameter. - /// - /// - /// - /// - /// Use no toolbars but allow the in-place container to leave its toolbars up by passing NULL as the pborderwidths parameter. - /// - /// - /// - /// - /// The BORDERWIDTHS structure used in this call would generally have been passed in a previous call to - /// IOleInPlaceUIWindow::RequestBorderSpace, which must have returned S_OK. - /// - /// - /// If an object must renegotiate space on the border, it can call IOleInPlaceUIWindow::SetBorderSpace again with the new - /// widths. If the call to IOleInPlaceUIWindow::SetBorderSpace fails, the object can do a full negotiation for border - /// space with calls to IOleInPlaceUIWindow::GetBorder, IOleInPlaceUIWindow::RequestBorderSpace, and IOleInPlaceUIWindow::SetBorderSpace. - /// - /// - /// Note While executing IOleInPlaceUIWindow::SetBorderSpace, do not make calls to the PeekMessage or GetMessage - /// functions, or a dialog box. Doing so may cause the system to deadlock. There are further restrictions on which OLE interface - /// methods and functions can be called from within IOleInPlaceUIWindow::SetBorderSpace. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplaceuiwindow-setborderspace HRESULT - // SetBorderSpace( LPCBORDERWIDTHS pborderwidths ); - new void SetBorderSpace(in RECT pborderwidths); - - /// Provides a direct channel of communication between the object and each of the frame and document windows. - /// A pointer to the IOleInPlaceActiveObject interface on the active in-place object. - /// - /// A pointer to a string containing a name that describes the object an embedding container can use in composing its window - /// title. It can be NULL if the object does not require the container to change its window titles. Containers should - /// ignore this parameter and always use their own name in the title bar. - /// - /// - /// - /// Generally, an embedded object should pass NULL for the pszObjName parameter (see Notes to Implementers below). - /// However, if you are working in conjunction with a container that does display the name of the in-place active object in its - /// title bar, then you should compose a string in the following form: <application name> – <object short-type name>. - /// - /// Notes to Callers - /// - /// IOleInPlaceUIWindow::SetActiveObject is called by the object to establish a direct communication link between itself - /// and the document and frame windows. - /// - /// - /// When deactivating, the object calls IOleInPlaceUIWindow::SetActiveObject, passing NULL for the pActiveObject - /// and pszObjName parameters. - /// - /// - /// An object must call IOleInPlaceUIWindow::SetActiveObject before calling IOleInPlaceFrame::SetMenu to give the - /// container the pointer to the active object. The container then uses this pointer in processing - /// IOleInPlaceFrame::SetMenu and to pass to OleSetMenuDescriptor. - /// - /// Notes to Implementers - /// - /// The Microsoft Windows User Interface Design Guide recommends that an in-place container ignore the pszObjName parameter - /// passed in this method. The guide says "The title bar is not affected by in-place activation. It always displays the - /// top-level container's name." - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplaceuiwindow-setactiveobject HRESULT - // SetActiveObject( IOleInPlaceActiveObject *pActiveObject, LPCOLESTR pszObjName ); - new void SetActiveObject([In] IOleInPlaceActiveObject pActiveObject, [MarshalAs(UnmanagedType.LPWStr)] string pszObjName); - - /// Enables the container to insert menu groups into the composite menu to be used during the in-place session. - /// A handle to an empty menu. - /// - /// A pointer to an OLEMENUGROUPWIDTHS array with six elements. The container fills in elements 0, 2, and 4 to reflect the - /// number of menu elements it provided in the File, View, and Window menu groups. - /// - /// - /// Notes to Callers - /// - /// This method is called by object applications when they are first being activated. They call it to insert their menus into - /// the frame-level user interface. - /// - /// - /// The object application asks the container to add its menus to the menu specified in hmenuShared and to set the group counts - /// in the OLEMENUGROUPWIDTHS array pointed to by lpMenuWidths. The object application then adds its own menus and counts. - /// Objects can call IOleInPlaceFrame::InsertMenus as many times as necessary to build up the composite menus. The - /// container should use the initial menu handle associated with the composite menu for all menu items in the drop-down menus. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplaceframe-insertmenus HRESULT InsertMenus( HMENU - // hmenuShared, LPOLEMENUGROUPWIDTHS lpMenuWidths ); - void InsertMenus(HMENU hmenuShared, ref OLEMENUGROUPWIDTHS lpMenuWidths); - - /// Adds a composite menu to the window frame containing the object being activated in place. - /// - /// A handle to the composite menu constructed by calls to IOleInPlaceFrame::InsertMenus and the InsertMenu function. - /// - /// A handle to the menu descriptor returned by the OleCreateMenuDescriptor function. - /// - /// A handle to a window owned by the object and to which menu messages, commands, and accelerators are to be sent. - /// - /// - /// Notes to Callers - /// - /// The object calls IOleInPlaceFrame::SetMenu to ask the container to install the composite menu structure set up by - /// calls to IOleInPlaceFrame::InsertMenus. - /// - /// Notes to Implementers - /// - /// An SDI container's implementation of this method should call the SetMenu function. An MDI container should send a - /// WM_MDISETMENU message, using hmenuShared as the menu to install. The container should call OleSetMenuDescriptor to install - /// the OLE dispatching code. - /// - /// - /// When deactivating, the container must call IOleInPlaceFrame::SetMenu, specifying NULL to remove the shared - /// menu. This is done to help minimize window repaints. The container should also call OleSetMenuDescriptor, specifying - /// NULL to unhook the dispatching code. Finally, the object application calls OleDestroyMenuDescriptor to free the data structure. - /// - /// - /// Note While executing IOleInPlaceFrame::SetMenu, do not make calls to the PeekMessage or GetMessage functions, - /// or a dialog box. Doing so may cause the system to deadlock. There are further restrictions on which OLE interface methods - /// and functions can be called from within IOleInPlaceFrame::SetMenu. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplaceframe-setmenu HRESULT SetMenu( HMENU - // hmenuShared, HOLEMENU holemenu, HWND hwndActiveObject ); - void SetMenu(HMENU hmenuShared, HOLEMENU holemenu, HWND hwndActiveObject); - - /// Removes a container's menu elements from the composite menu. - /// - /// A handle to the in-place composite menu that was constructed by calls to IOleInPlaceFrame::InsertMenus and the InsertMenu function. - /// - /// - /// - /// The object should always give the container a chance to remove its menu elements from the composite menu before deactivating - /// the shared user interface. - /// - /// Notes to Callers - /// This method is called by the object application while it is being UI-deactivated to remove its menus. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplaceframe-removemenus HRESULT RemoveMenus( HMENU - // hmenuShared ); - void RemoveMenus(HMENU hmenuShared); - - /// Sets and displays status text about the in-place object in the container's frame window status line. - /// The message to be displayed. - /// - /// Notes to Callers - /// - /// You should call IOleInPlaceFrame::SetStatusText when you need to ask the container to display object text in its - /// frame's status line, if it has one. Because the container's frame window owns the status line, calling - /// IOleInPlaceFrame::SetStatusText is the only way an object can display status information in the container's frame - /// window. If the container refuses the object's request, the object application can, however, negotiate for border space to - /// display its own status window. - /// - /// - /// When switching between menus owned by the container and the in-place active object, the status bar text is not reflected - /// properly if the object does not call the container's IOleInPlaceFrame::SetStatusText method. For example, if, during - /// an in-place session, the user were to select the File menu, the status bar would reflect the action that would occur - /// if the user selected this menu. If the user then selects the Edit menu (which is owned by the in-place object), the - /// status bar text would not change unless the IOleInPlaceFrame::SetStatusText happened to be called. This is because - /// there is no way for the container to recognize that one of the object's menus has been made active because all the messages - /// that the container would trap are now going to the object. - /// - /// Notes to Implementers - /// - /// To avoid potential problems, all objects being activated in place should process the WM_MENUSELECT message and call - /// IOleInPlaceFrame::SetStatusText —even if the object does not usually provide status information (in which case the - /// object can just pass a NULL string for the requested status text). - /// - /// - /// Note While executing IOleInPlaceFrame::SetStatusText, do not make calls to the PeekMessage or GetMessage - /// functions, or a dialog box. Doing so may cause the system to deadlock. There are further restrictions on which OLE interface - /// methods and functions can be called from within IOleInPlaceUIWindow::GetBorder. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplaceframe-setstatustext HRESULT SetStatusText( - // LPCOLESTR pszStatusText ); - void SetStatusText([MarshalAs(UnmanagedType.LPWStr)] string pszStatusText); - - /// Enables or disables a frame's modeless dialog boxes. - /// - /// Specifies whether the modeless dialog box windows are to be enabled ( TRUE) or disabled ( FALSE). - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplaceframe-enablemodeless HRESULT EnableModeless( - // BOOL fEnable ); - void EnableModeless([MarshalAs(UnmanagedType.Bool)] bool fEnable); - - /// Translates accelerator keystrokes intended for the container's frame while an object is active in place. - /// A pointer to the MSG structure that contains the keystroke message. - /// - /// The command identifier value corresponding to the keystroke in the container-provided accelerator table. Containers should - /// use this value instead of translating again. - /// - /// - /// Notes to Callers - /// - /// The IOleInPlaceFrame::TranslateAccelerator method is called indirectly by OleTranslateAccelerator when a keystroke - /// accelerator intended for the container (frame) is received. - /// - /// Notes to Implementers - /// - /// The container application should perform its usual accelerator processing, or use wID directly, and then return, indicating - /// whether the keystroke accelerator was processed. If the container is an MDI application and the TranslateAccelerator - /// function fails, the container can call the TranslateMDISysAccel function, just as it does for its usual message processing. - /// - /// - /// In-place objects should be given first chance at translating accelerator messages. However, because objects implemented by - /// DLL object applications do not have their own message pump, they receive their messages from the container's message queue. - /// To ensure that the object has first chance at translating messages, a container should always call - /// IOleInPlaceFrame::TranslateAccelerator before doing its own accelerator translation. Conversely, an executable object - /// application should call OleTranslateAccelerator after calling TranslateAccelerator, calling TranslateMessage and - /// DispatchMessage only if both translation functions fail. - /// - /// - /// You should define accelerator tables for containers so they will work properly with object applications that do their own - /// accelerator keystroke translations. Tables should be defined as follows. - /// - /// - /// This is the most common way to describe keyboard accelerators. Failure to do so can result in keystrokes being lost or sent - /// to the wrong object during an in-place session. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplaceframe-translateaccelerator HRESULT - // TranslateAccelerator( LPMSG lpmsg, WORD wID ); - void TranslateAccelerator(in MSG lpmsg, in ushort wID); - } - - /// - /// - /// Manages the activation and deactivation of in-place objects, and determines how much of the in-place object should be visible. - /// - /// You can obtain a pointer to IOleInPlaceObject by calling IUnknown::QueryInterface on IOleObject. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nn-oleidl-ioleinplaceobject - [PInvokeData("oleidl.h", MSDNShortId = "NN:oleidl.IOleInPlaceObject")] - [ComImport, Guid("00000113-0000-0000-C000-000000000046"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] - public interface IOleInPlaceObject : IOleWindow - { - /// - /// Retrieves a handle to one of the windows participating in in-place activation (frame, document, parent, or in-place object window). - /// - /// A pointer to a variable that receives the window handle. - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// E_FAIL - /// The object is windowless. - /// - /// - /// E_OUTOFMEMORY - /// There is insufficient memory available for this operation. - /// - /// - /// E_UNEXPECTED - /// An unexpected error has occurred. - /// - /// - /// - /// - /// - /// Five types of windows comprise the windows hierarchy. When a object is active in place, it has access to some or all of - /// these windows. - /// - /// - /// - /// Window - /// Description - /// - /// - /// Frame - /// The outermost main window where the container application's main menu resides. - /// - /// - /// Document - /// The window that displays the compound document containing the embedded object to the user. - /// - /// - /// Pane - /// - /// The subwindow of the document window that contains the object's view. Applicable only for applications with split-pane windows. - /// - /// - /// - /// Parent - /// - /// The container window that contains that object's view. The object application installs its window as a child of this window. - /// - /// - /// - /// In-place - /// - /// The window containing the active in-place object. The object application creates this window and installs it as a child of - /// its hatch window, which is a child of the container's parent window. - /// - /// - /// - /// - /// Each type of window has a different role in the in-place activation architecture. However, it is not necessary to employ a - /// separate physical window for each type. Many container applications use the same window for their frame, document, pane, and - /// parent windows. - /// - /// - [PreserveSig] - new HRESULT GetWindow(out HWND phwnd); - - /// Determines whether context-sensitive help mode should be entered during an in-place activation session. - /// - /// if help mode should be entered; if it should be exited. - /// - /// - /// - /// This method returns S_OK if the help mode was entered or exited successfully, depending on the value passed in . Other possible return values include the following.
- /// - /// - /// - /// Return code - /// Description - /// - /// - /// E_INVALIDARG - /// The specified value is not valid. - /// - /// - /// E_OUTOFMEMORY - /// There is insufficient memory available for this operation. - /// - /// - /// E_UNEXPECTED - /// An unexpected error has occurred. - /// - /// - /// - /// - /// Applications can invoke context-sensitive help when the user: - /// - /// presses SHIFT+F1, then clicks a topic - /// presses F1 when a menu item is selected - /// - /// - /// When SHIFT+F1 is pressed, either the frame or active object can receive the keystrokes. If the container's frame receives - /// the keystrokes, it calls its containing document's IOleWindow::ContextSensitiveHelp method with set to . This propagates the help state to all of its in-place objects so they can - /// correctly handle the mouse click or WM_COMMAND. - /// - /// - /// If an active object receives the SHIFT+F1 keystrokes, it calls the container's IOleWindow::ContextSensitiveHelp method with - /// set to , which then recursively calls each of its in-place sites until - /// there are no more to be notified. The container then calls its document's or frame's IOleWindow::ContextSensitiveHelp method - /// with set to . - /// - /// When in context-sensitive help mode, an object that receives the mouse click can either: - /// - /// Ignore the click if it does not support context-sensitive help. - /// - /// Tell all the other objects to exit context-sensitive help mode with ContextSensitiveHelp set to FALSE and then provide help - /// for that context. - /// - /// - /// - /// An object in context-sensitive help mode that receives a WM_COMMAND should tell all the other in-place objects to exit - /// context-sensitive help mode and then provide help for the command. - /// - /// - /// If a container application is to support context-sensitive help on menu items, it must either provide its own message filter - /// so that it can intercept the F1 key or ask the OLE library to add a message filter by calling OleSetMenuDescriptor, passing - /// valid, non-NULL values for the lpFrame and lpActiveObj parameters. - /// - /// - [PreserveSig] - new HRESULT ContextSensitiveHelp([MarshalAs(UnmanagedType.Bool)] bool fEnterMode); - - /// Deactivates an active in-place object and discards the object's undo state. - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// E_UNEXPECTED - /// An unexpected error occurred. - /// - /// - /// - /// - /// Notes to Callers - /// - /// This method is called by an active object's immediate container to deactivate the active object and discard its undo state. - /// - /// Notes to Implementers - /// - /// On return from IOleInPlaceObject::InPlaceDeactivate, the object discards its undo state. The object application - /// should not shut down immediately after this call. Instead, it should wait for an explicit call to IOleObject::Close or for - /// the object's reference count to reach zero. - /// - /// - /// Before deactivating, the object application should give the container a chance to put its user interface back on the frame - /// window by calling IOleInPlaceSite::OnUIDeactivate. - /// - /// - /// If the in-place user interface is still visible during the call to IOleInPlaceObject::InPlaceDeactivate, the object - /// application should call its own IOleInPlaceObject::InPlaceDeactivate method to hide the user interface. The in-place - /// user interface can be optionally destroyed during calls to IOleInPlaceObject::InPlaceDeactivate and - /// IOleInPlaceObject::InPlaceDeactivate. But if the user interface has not already been destroyed when the container - /// calls IOleObject::Close, then it must be destroyed during the call to IOleObject::Close. - /// - /// - /// During the call to IOleObject::Close, the object should check to see whether it is still active in place. If so, it should - /// call IOleInPlaceObject::InPlaceDeactivate. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplaceobject-inplacedeactivate HRESULT InPlaceDeactivate(); - [PreserveSig] - HRESULT InPlaceDeactivate(); - - /// Deactivates and removes the user interface of an active in-place object. - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// E_UNEXPECTED - /// An unexpected error has occurred. - /// - /// - /// - /// - /// Notes to Callers - /// - /// This method is called by the object's immediate container when, for example, the user has clicked in the client area outside - /// the object. - /// - /// - /// If the container has called IOleInPlaceObject::UIDeactivate, it should later call - /// IOleInPlaceObject::InPlaceDeactivate to properly clean up resources. The container can assume that stopping or releasing the - /// object cleans up resources if necessary. The object must be prepared to do so if IOleInPlaceObject::InPlaceDeactivate - /// has not been called. but either IOleInPlaceObject::UIDeactivate or IOleObject::Close has been called. - /// - /// Notes to Implementers - /// - /// Resources such as menus and windows can be either cleaned up or kept in a hidden state until your object is completely - /// deactivated by calls to either IOleInPlaceObject::InPlaceDeactivate or IOleObject::Close. The object application must call - /// IOleInPlaceSite::OnUIDeactivate before doing anything with the composite menus so that the container can first be detached - /// from the frame window. On deactivating the in-place object's user interface, the object is left in a ready state so it can - /// be quickly reactivated. The object stays in this state until the undo state of the document changes. The container should - /// then call IOleInPlaceObject::InPlaceDeactivate to tell the object to discard its undo state. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplaceobject-uideactivate HRESULT UIDeactivate(); - [PreserveSig] - HRESULT UIDeactivate(); - - /// Specifies how much of the in-place object is to be visible. - /// - /// A pointer to the RECT structure containing the position of the in-place object using the client coordinates of its parent window. - /// - /// - /// A pointer to the outer rectangle containing the in-place object's position rectangle (lprcPosRect). This rectangle is - /// relative to the client area of the object's parent window. - /// - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// E_INVALIDARG - /// The specified pointer is invalid. - /// - /// - /// E_OUTOFMEMORY - /// There is insufficient memory available for the operation. - /// - /// - /// E_UNEXPECTED - /// An unexpected error has occurred. - /// - /// - /// - /// - /// It is possible for lprcClipRect to change without lprcPosRect changing. - /// - /// The size of an in-place object's rectangle is always calculated in pixels. This is different from other OLE object's - /// visualizations, which are in HIMETRIC. - /// - /// - /// Note While executing IOleInPlaceObject::SetObjectRects, do not make calls to the PeekMessage or GetMessage - /// functions, or a dialog box. Doing so may cause the system to deadlock. There are further restrictions on which OLE interface - /// methods and functions can be called from within IOleInPlaceObject::SetObjectRects. - /// - /// Notes to Callers - /// - /// The container should call IOleInPlaceObject::SetObjectRects whenever the window position of the in-place object - /// and/or the visible part of the in-place object changes. - /// - /// Notes to Implementers - /// - /// The object must size its in-place window to match the intersection of lprcPosRect and lprcClipRect. The object must also - /// draw its contents into the object's in-place window so that proper clipping takes place. - /// - /// - /// The object should compare its width and height with those provided by its container (conveyed through lprcPosRect). If the - /// comparison does not result in a match, the container is applying scaling to the object. The object must then decide whether - /// it should continue the in-place editing in the scale/zoom mode or deactivate. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplaceobject-setobjectrects HRESULT SetObjectRects( - // LPCRECT lprcPosRect, LPCRECT lprcClipRect ); - [PreserveSig] - HRESULT SetObjectRects(in RECT lprcPosRect, in RECT lprcClipRect); - - /// Reactivates a previously deactivated object, undoing the last state of the object. - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// E_NOTUNDOABLE - /// The undo state is not available. - /// - /// - /// E_OUTOFMEMORY - /// There is insufficient memory available for the operation. - /// - /// - /// E_UNEXPECTED - /// An unexpected error has occurred. - /// - /// - /// - /// - /// If the user chooses the Undo command before the undo state of the object is lost, the object's immediate container - /// calls IOleInPlaceObject::ReactivateAndUndo to activate the user interface, carry out the undo operation, and return - /// the object to the active state. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplaceobject-reactivateandundo HRESULT ReactivateAndUndo(); - [PreserveSig] - HRESULT ReactivateAndUndo(); - } - - /// - /// - /// Manages the interaction between the container and the object's in-place client site. Recall that the client site is the display - /// site for embedded objects, and provides position and conceptual information about the object. - /// - /// - /// This interface provides methods that manage in-place objects. With IOleInPlaceSite, you can determine if an object can be - /// activated and manage its activation and deactivation. You can notify the container when one of its objects is being activated - /// and inform the container that a composite menu will replace the container's regular menu. It provides methods that make it - /// possible for the in-place object to retrieve the window object hierarchy, and the position in the parent window where the object - /// should place its in-place activation window. Finally, it determines how the container scrolls the object, manages the object - /// undo state, and notifies the object when its borders have changed. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nn-oleidl-ioleinplacesite - [PInvokeData("oleidl.h", MSDNShortId = "NN:oleidl.IOleInPlaceSite")] - [ComImport, Guid("00000119-0000-0000-C000-000000000046"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] - public interface IOleInPlaceSite : IOleWindow - { - /// - /// Retrieves a handle to one of the windows participating in in-place activation (frame, document, parent, or in-place object window). - /// - /// A pointer to a variable that receives the window handle. - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// E_FAIL - /// The object is windowless. - /// - /// - /// E_OUTOFMEMORY - /// There is insufficient memory available for this operation. - /// - /// - /// E_UNEXPECTED - /// An unexpected error has occurred. - /// - /// - /// - /// - /// - /// Five types of windows comprise the windows hierarchy. When a object is active in place, it has access to some or all of - /// these windows. - /// - /// - /// - /// Window - /// Description - /// - /// - /// Frame - /// The outermost main window where the container application's main menu resides. - /// - /// - /// Document - /// The window that displays the compound document containing the embedded object to the user. - /// - /// - /// Pane - /// - /// The subwindow of the document window that contains the object's view. Applicable only for applications with split-pane windows. - /// - /// - /// - /// Parent - /// - /// The container window that contains that object's view. The object application installs its window as a child of this window. - /// - /// - /// - /// In-place - /// - /// The window containing the active in-place object. The object application creates this window and installs it as a child of - /// its hatch window, which is a child of the container's parent window. - /// - /// - /// - /// - /// Each type of window has a different role in the in-place activation architecture. However, it is not necessary to employ a - /// separate physical window for each type. Many container applications use the same window for their frame, document, pane, and - /// parent windows. - /// - /// - [PreserveSig] - new HRESULT GetWindow(out HWND phwnd); - - /// Determines whether context-sensitive help mode should be entered during an in-place activation session. - /// - /// if help mode should be entered; if it should be exited. - /// - /// - /// - /// This method returns S_OK if the help mode was entered or exited successfully, depending on the value passed in . Other possible return values include the following.
- /// - /// - /// - /// Return code - /// Description - /// - /// - /// E_INVALIDARG - /// The specified value is not valid. - /// - /// - /// E_OUTOFMEMORY - /// There is insufficient memory available for this operation. - /// - /// - /// E_UNEXPECTED - /// An unexpected error has occurred. - /// - /// - /// - /// - /// Applications can invoke context-sensitive help when the user: - /// - /// presses SHIFT+F1, then clicks a topic - /// presses F1 when a menu item is selected - /// - /// - /// When SHIFT+F1 is pressed, either the frame or active object can receive the keystrokes. If the container's frame receives - /// the keystrokes, it calls its containing document's IOleWindow::ContextSensitiveHelp method with set to . This propagates the help state to all of its in-place objects so they can - /// correctly handle the mouse click or WM_COMMAND. - /// - /// - /// If an active object receives the SHIFT+F1 keystrokes, it calls the container's IOleWindow::ContextSensitiveHelp method with - /// set to , which then recursively calls each of its in-place sites until - /// there are no more to be notified. The container then calls its document's or frame's IOleWindow::ContextSensitiveHelp method - /// with set to . - /// - /// When in context-sensitive help mode, an object that receives the mouse click can either: - /// - /// Ignore the click if it does not support context-sensitive help. - /// - /// Tell all the other objects to exit context-sensitive help mode with ContextSensitiveHelp set to FALSE and then provide help - /// for that context. - /// - /// - /// - /// An object in context-sensitive help mode that receives a WM_COMMAND should tell all the other in-place objects to exit - /// context-sensitive help mode and then provide help for the command. - /// - /// - /// If a container application is to support context-sensitive help on menu items, it must either provide its own message filter - /// so that it can intercept the F1 key or ask the OLE library to add a message filter by calling OleSetMenuDescriptor, passing - /// valid, non-NULL values for the lpFrame and lpActiveObj parameters. - /// - /// - [PreserveSig] - new HRESULT ContextSensitiveHelp([MarshalAs(UnmanagedType.Bool)] bool fEnterMode); - - /// Determines whether the container can activate the object in place. - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// S_FALSE - /// The container does not allow in-place activation for this object. - /// - /// - /// E_UNEXPECTED - /// An unexpected error has occurred. - /// - /// - /// - /// - /// Only objects being displayed as DVASPECT_CONTENT can be activated in place. - /// Notes to Callers - /// - /// CanInPlaceActivate is called by the client site's immediate child object when this object must activate in place. - /// This function allows the container application to accept or refuse the activation request. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplacesite-caninplaceactivate HRESULT CanInPlaceActivate(); - [PreserveSig] - HRESULT CanInPlaceActivate(); - - /// Notifies the container that one of its objects is being activated in place. - /// - /// - /// This method returns S_OK if the container allows the in-place activation. Other possible return values include the following. - /// - /// - /// - /// Return code - /// Description - /// - /// - /// E_UNEXPECTED - /// An unexpected error has occurred. - /// - /// - /// - /// - /// Notes to Callers - /// - /// OnInPlaceActivate is called by the active embedded object when it is activated in-place for the first time. The - /// container should note that the object is becoming active. - /// - /// Notes to Implementers - /// - /// A container that supports linking to embedded objects must properly manage the running of its in-place objects when they are - /// UI-inactive and running in the hidden state. To reactivate the in-place object quickly, a container should not call - /// IOleObject::Close until the container's IOleInPlaceSite::DeactivateAndUndo method is called. To help protect against the - /// object being left in an unstable state if a linking client updates silently, the container should call OleLockRunning to - /// lock the object in the running state. This prevents the hidden in-place object from shutting down before it can be saved in - /// its container. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplacesite-oninplaceactivate HRESULT OnInPlaceActivate(); - [PreserveSig] - HRESULT OnInPlaceActivate(); - - /// - /// Notifies the container that the object is about to be activated in place and that the object is going to replace the - /// container's main menu with an in-place composite menu. - /// - /// - /// - /// This method returns S_OK if the container allows the in-place activation. Other possible return values include the following. - /// - /// - /// - /// Return code - /// Description - /// - /// - /// E_UNEXPECTED - /// An unexpected error has occurred. - /// - /// - /// - /// - /// Notes to Callers - /// The in-place object calls IOleInPlaceSite::OnUIActivate just before activating its user interface. - /// Notes to Implementers - /// - /// The container should remove any user interface associated with its own activation. If the container is itself an embedded - /// object, it should remove its document-level user interface. - /// - /// - /// If there is already an object active in place in the same document, the container should call - /// IOleInPlaceObject::UIDeactivate before calling OnUIDeactivate. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplacesite-onuiactivate HRESULT OnUIActivate(); - [PreserveSig] - HRESULT OnUIActivate(); - - /// - /// Enables an in-place object to retrieve the window interfaces that form the window object hierarchy, and the position in the - /// parent window where the object's in-place activation window should be located. - /// - /// - /// A pointer to an IOleInPlaceFrame pointer variable that receives the interface pointer to the frame. If an error occurs, the - /// implementation must set ppFrame to NULL. - /// - /// - /// A pointer to an IOleInPlaceUIWindow pointer variable that receives the interface pointer to the document window. If the - /// document window is the same as the frame window, ppDoc is set to NULL. In this case, the object can only use ppFrame - /// or border negotiation. If an error is returned, the implementation must set ppDoc to NULL. - /// - /// - /// A pointer to a RECT structure for the rectangle containing the position of the in-place object in the client coordinates of - /// its parent window. If an error is returned, this parameter must be set to NULL. - /// - /// - /// A pointer to a RECT structure for the outer rectangle containing the in-place object's position rectangle (lprcPosRect). - /// This rectangle is relative to the client area of the object's parent window. If an error is returned, this parameter must be - /// set to NULL. - /// - /// - /// A pointer to an OLEINPLACEFRAMEINFO structure the container is to fill in with appropriate data. If an error is returned, - /// this parameter must be set to NULL. - /// - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// E_INVALIDARG - /// One or more of the supplied pointers is invalid. - /// - /// - /// E_UNEXPECTED - /// An unexpected error has occurred. - /// - /// - /// - /// - /// - /// The OLEINPLACEFRAMEINFO structure provides data needed by OLE to dispatch keystroke accelerators to a container frame while - /// an object is active in place. - /// - /// - /// When an object is activated, it calls GetWindowContext from its container. The container returns the handle to its - /// in-place accelerator table through the OLEINPLACEFRAMEINFO structure. Before calling GetWindowContext, the object - /// must provide the size of the OLEINPLACEFRAMEINFO structure by filling in the cb member, pointed to by lpFrameInfo. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplacesite-getwindowcontext HRESULT - // GetWindowContext( IOleInPlaceFrame **ppFrame, IOleInPlaceUIWindow **ppDoc, LPRECT lprcPosRect, LPRECT lprcClipRect, - // LPOLEINPLACEFRAMEINFO lpFrameInfo ); - [PreserveSig] - unsafe HRESULT GetWindowContext(out IOleInPlaceFrame ppFrame, out IOleInPlaceUIWindow ppDoc, [Out] RECT* lprcPosRect, [Out] RECT* lprcClipRect, [Out] OLEINPLACEFRAMEINFO* lpFrameInfo); - - /// Instructs the container to scroll the view of the object by the specified number of pixels. - /// The number of pixels by which to scroll in the X and Y directions. - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// E_INVALIDARG - /// The specified pointer is not valid. - /// - /// - /// E_UNEXPECTED - /// An unexpected error has occurred. - /// - /// - /// - /// - /// - /// As a result of scrolling, the object's visible rectangle can change. If that happens, the container should give the new - /// clipping rectangle to the object by calling IOleInPlaceObject::SetObjectRects. The intersection of the lprcClipRect and - /// lprcPosRect rectangles gives the new visible rectangle. See IOleInPlaceSite::GetWindowContext for more information. - /// - /// Notes to Callers - /// Called by an active, in-place object when it is asking the container to scroll. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplacesite-scroll HRESULT Scroll( SIZE scrollExtant ); - [PreserveSig] - HRESULT Scroll(SIZE scrollExtant); - - /// - /// Notifies the container that it should reinstall its user interface and take focus, and whether the object has an undoable state. - /// - /// Specifies whether the object can undo changes (TRUE) or not (FALSE). - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// E_UNEXPECTED - /// An unexpected error has occurred. - /// - /// - /// - /// - /// - /// The object indicates whether it can undo changes through the fUndoable flag. If the object can undo changes, the container - /// can (by the user invoking the Edit Undo command) call the IOleInPlaceObject::ReactivateAndUndo method to undo the changes. - /// - /// Notes to Callers - /// - /// IOleInPlaceSite::OnUIDeactivate is called by the site's immediate child object when it is deactivating to notify the - /// container that it should reinstall its own user interface components and take focus. The container should wait for the call - /// to IOleInPlaceSite::OnUIDeactivate to complete before fully cleaning up and destroying any composite submenus. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplacesite-onuideactivate HRESULT OnUIDeactivate( - // BOOL fUndoable ); - [PreserveSig] - HRESULT OnUIDeactivate([MarshalAs(UnmanagedType.Bool)] bool fUndoable); - - /// Notifies the container that the object is no longer active in place. - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// E_UNEXPECTED - /// An unexpected error has occurred. - /// - /// - /// - /// - /// Notes to Callers - /// - /// OnInPlaceDeactivate is called by an in-place object when it is fully deactivated. This function notifies the - /// container that the object has been deactivated, and it gives the container a chance to run code pertinent to the object's - /// deactivation. In particular, OnInPlaceDeactivate is called as a result of IOleInPlaceObject::InPlaceDeactivate being - /// called. Calling OnInPlaceDeactivate indicates that the object can no longer support Undo. - /// - /// Notes to Implementers - /// - /// If the container is holding pointers to the IOleInPlaceObject and IOleInPlaceActiveObject interface implementations, it - /// should release them after the OnInPlaceDeactivate call. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplacesite-oninplacedeactivate HRESULT OnInPlaceDeactivate(); - [PreserveSig] - HRESULT OnInPlaceDeactivate(); - - /// Instructs the container to discard its undo state. The container should not call IOleInPlaceObject::ReActivateAndUndo. - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// E_UNEXPECTED - /// An unexpected error has occurred. - /// - /// - /// - /// - /// - /// If an object is activated in place and the object's associated object application maintains only one level of undo, there is - /// no need to have more than one entry on the undo stack. That is, after a change has been made to the active object that - /// invalidates its undo state saved by the container, there is no need to maintain this undo state in the container. - /// - /// Notes to Callers - /// - /// DiscardUndoState is called by the active object while performing some action that would discard the undo state of the - /// object. The in-place object calls this method to notify the container to discard the object's last saved undo state. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplacesite-discardundostate HRESULT DiscardUndoState(); - [PreserveSig] - HRESULT DiscardUndoState(); - - /// Deactivates the object, ends the in-place session, and reverts to the container's saved undo state. - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// E_UNEXPECTED - /// An unexpected error has occurred. - /// - /// - /// - /// - /// Notes to Callers - /// Called by the active object when the user invokes undo just after activating the object. - /// Notes to Implementers - /// - /// Upon completion of this call, the container should call IOleInPlaceObject::UIDeactivate to remove the user interface for the - /// object, activate itself, and undo. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplacesite-deactivateandundo HRESULT DeactivateAndUndo(); - [PreserveSig] - HRESULT DeactivateAndUndo(); - - /// Notifies the container that the object extents have changed. - /// - /// A pointer a RECT structure that contains the position of the in-place object in the client coordinates of its parent window. - /// - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// E_INVALIDARG - /// The supplied pointer is invalid. - /// - /// - /// E_UNEXPECTED - /// An unexpected error occurred. - /// - /// - /// - /// - /// Notes to Callers - /// The OnPosRectChange method is called by the in-place object. - /// Notes to Implementers - /// - /// When the in-place object calls OnPosRectChange, the container must call IOleInPlaceObject::SetObjectRects to specify - /// the new position of the in-place window and the clipping rectangle. Only then does the object resize its window. - /// - /// - /// In most cases, the object grows to the right and/or down. There could be cases where the object grows to the left and/or up, - /// as conveyed through lprcPosRect. It is also possible to change the object's position without changing its size. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplacesite-onposrectchange HRESULT OnPosRectChange( - // LPCRECT lprcPosRect ); - [PreserveSig] - HRESULT OnPosRectChange(in RECT lprcPosRect); - } - - /// - /// Implemented by container applications and used by object applications to negotiate border space on the document or frame window. - /// The container provides a RECT structure in which the object can place toolbars and other similar controls, determines if tools - /// can in fact be installed around the object's window frame, allocates space for the border, and establishes a communication - /// channel between the object and each frame and document window. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nn-oleidl-ioleinplaceuiwindow - [PInvokeData("oleidl.h", MSDNShortId = "3cfb31aa-9746-438c-af64-8236c170fe88")] - [ComImport, Guid("00000115-0000-0000-C000-000000000046"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] - public interface IOleInPlaceUIWindow : IOleWindow - { - /// - /// Retrieves a handle to one of the windows participating in in-place activation (frame, document, parent, or in-place object window). - /// - /// A pointer to a variable that receives the window handle. - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// E_FAIL - /// The object is windowless. - /// - /// - /// E_OUTOFMEMORY - /// There is insufficient memory available for this operation. - /// - /// - /// E_UNEXPECTED - /// An unexpected error has occurred. - /// - /// - /// - /// - /// - /// Five types of windows comprise the windows hierarchy. When a object is active in place, it has access to some or all of - /// these windows. - /// - /// - /// - /// Window - /// Description - /// - /// - /// Frame - /// The outermost main window where the container application's main menu resides. - /// - /// - /// Document - /// The window that displays the compound document containing the embedded object to the user. - /// - /// - /// Pane - /// - /// The subwindow of the document window that contains the object's view. Applicable only for applications with split-pane windows. - /// - /// - /// - /// Parent - /// - /// The container window that contains that object's view. The object application installs its window as a child of this window. - /// - /// - /// - /// In-place - /// - /// The window containing the active in-place object. The object application creates this window and installs it as a child of - /// its hatch window, which is a child of the container's parent window. - /// - /// - /// - /// - /// Each type of window has a different role in the in-place activation architecture. However, it is not necessary to employ a - /// separate physical window for each type. Many container applications use the same window for their frame, document, pane, and - /// parent windows. - /// - /// - [PreserveSig] - new HRESULT GetWindow(out HWND phwnd); - - /// Determines whether context-sensitive help mode should be entered during an in-place activation session. - /// - /// if help mode should be entered; if it should be exited. - /// - /// - /// - /// This method returns S_OK if the help mode was entered or exited successfully, depending on the value passed in . Other possible return values include the following.
- /// - /// - /// - /// Return code - /// Description - /// - /// - /// E_INVALIDARG - /// The specified value is not valid. - /// - /// - /// E_OUTOFMEMORY - /// There is insufficient memory available for this operation. - /// - /// - /// E_UNEXPECTED - /// An unexpected error has occurred. - /// - /// - /// - /// - /// Applications can invoke context-sensitive help when the user: - /// - /// presses SHIFT+F1, then clicks a topic - /// presses F1 when a menu item is selected - /// - /// - /// When SHIFT+F1 is pressed, either the frame or active object can receive the keystrokes. If the container's frame receives - /// the keystrokes, it calls its containing document's IOleWindow::ContextSensitiveHelp method with set to . This propagates the help state to all of its in-place objects so they can - /// correctly handle the mouse click or WM_COMMAND. - /// - /// - /// If an active object receives the SHIFT+F1 keystrokes, it calls the container's IOleWindow::ContextSensitiveHelp method with - /// set to , which then recursively calls each of its in-place sites until - /// there are no more to be notified. The container then calls its document's or frame's IOleWindow::ContextSensitiveHelp method - /// with set to . - /// - /// When in context-sensitive help mode, an object that receives the mouse click can either: - /// - /// Ignore the click if it does not support context-sensitive help. - /// - /// Tell all the other objects to exit context-sensitive help mode with ContextSensitiveHelp set to FALSE and then provide help - /// for that context. - /// - /// - /// - /// An object in context-sensitive help mode that receives a WM_COMMAND should tell all the other in-place objects to exit - /// context-sensitive help mode and then provide help for the command. - /// - /// - /// If a container application is to support context-sensitive help on menu items, it must either provide its own message filter - /// so that it can intercept the F1 key or ask the OLE library to add a message filter by calling OleSetMenuDescriptor, passing - /// valid, non-NULL values for the lpFrame and lpActiveObj parameters. - /// - /// - [PreserveSig] - new HRESULT ContextSensitiveHelp([MarshalAs(UnmanagedType.Bool)] bool fEnterMode); - - /// Retrieves the outer rectange for toolbars and controls while the object is active in place. - /// - /// A pointer to a RECT structure where the outer rectangle is to be returned. The structure's coordinates are relative to the - /// window being represented by the interface. - /// - /// - /// Notes to Callers - /// - /// The IOleInPlaceUIWindow::GetBorder function, when called on a document or frame window object, returns the outer - /// rectangle (relative to the window) where the object can put toolbars or similar controls. - /// - /// - /// If the object is to install these tools, it should negotiate space for the tools within this rectangle using - /// IOleInPlaceUIWindow::RequestBorderSpace and then call IOleInPlaceUIWindow::SetBorderSpace to get this space allocated. - /// - /// - /// Note While executing IOleInPlaceUIWindow::GetBorder, do not make calls to the PeekMessage or GetMessage - /// functions, or a dialog box. Doing so may cause the system to deadlock. There are further restrictions on which OLE interface - /// methods and functions can be called from within GetBorder. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplaceuiwindow-getborder HRESULT GetBorder( LPRECT - // lprectBorder ); - void GetBorder(out RECT lprectBorder); - - /// - /// Determines whether there is space available for tools to be installed around the object's window frame while the object is - /// active in place. - /// - /// - /// A pointer to a BORDERWIDTHS structure containing the requested widths (in pixels) needed on each side of the window for the tools. - /// - /// - /// Notes to Callers - /// - /// The active in-place object calls IOleInPlaceUIWindow::RequestBorderSpace to ask if tools can be installed inside the - /// window frame. These tools would be allocated between the rectangle returned by IOleInPlaceUIWindow::GetBorder and the - /// BORDERWIDTHS structure specified in the argument to this call. - /// - /// - /// The space for the tools is not actually allocated to the object until it calls IOleInPlaceUIWindow::SetBorderSpace, allowing - /// the object to negotiate for space (such as while dragging toolbars around), but deferring the moving of tools until the - /// action is completed. - /// - /// - /// The object can install these tools by passing the width in pixels that is to be used on each side. For example, if the - /// object required 10 pixels on the top, 0 pixels on the bottom, and 5 pixels on the left and right sides, it would pass the - /// following BORDERWIDTHS structure to IOleInPlaceUIWindow::RequestBorderSpace: - /// - /// - /// Note While executing IOleInPlaceUIWindow::RequestBorderSpace, do not make calls to the PeekMessage or - /// GetMessage functions, or a dialog box. Doing so may cause the system to deadlock. There are further restrictions on which - /// OLE interface methods and functions can be called from within IOleInPlaceUIWindow::RequestBorderSpace. - /// - /// Notes to Implementers - /// - /// If the amount of space an active object uses for its toolbars is irrelevant to the container, it can simply return NOERROR - /// as shown in the following IOleInPlaceUIWindow::RequestBorderSpace example. Containers should not unduly restrict the - /// display of tools by an active in-place object. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplaceuiwindow-requestborderspace HRESULT - // RequestBorderSpace( LPCBORDERWIDTHS pborderwidths ); - void RequestBorderSpace(in RECT pborderwidths); - - /// Allocates space for the border requested in the call to IOleInPlaceUIWindow::RequestBorderSpace. - /// - /// Pointer to a BORDERWIDTHS structure containing the requested width of the tools, in pixels. It can be NULL, - /// indicating the object does not need any space. - /// - /// - /// The object must call IOleInPlaceUIWindow::SetBorderSpace. It can do any one of the following: - /// - /// - /// Use its own toolbars, requesting border space of a specific size. - /// - /// - /// - /// Use no toolbars, but force the container to remove its toolbars by passing a valid BORDERWIDTHS structure containing nothing - /// but zeros in the pborderwidths parameter. - /// - /// - /// - /// - /// Use no toolbars but allow the in-place container to leave its toolbars up by passing NULL as the pborderwidths parameter. - /// - /// - /// - /// - /// The BORDERWIDTHS structure used in this call would generally have been passed in a previous call to - /// IOleInPlaceUIWindow::RequestBorderSpace, which must have returned S_OK. - /// - /// - /// If an object must renegotiate space on the border, it can call IOleInPlaceUIWindow::SetBorderSpace again with the new - /// widths. If the call to IOleInPlaceUIWindow::SetBorderSpace fails, the object can do a full negotiation for border - /// space with calls to IOleInPlaceUIWindow::GetBorder, IOleInPlaceUIWindow::RequestBorderSpace, and IOleInPlaceUIWindow::SetBorderSpace. - /// - /// - /// Note While executing IOleInPlaceUIWindow::SetBorderSpace, do not make calls to the PeekMessage or GetMessage - /// functions, or a dialog box. Doing so may cause the system to deadlock. There are further restrictions on which OLE interface - /// methods and functions can be called from within IOleInPlaceUIWindow::SetBorderSpace. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplaceuiwindow-setborderspace HRESULT - // SetBorderSpace( LPCBORDERWIDTHS pborderwidths ); - void SetBorderSpace(in RECT pborderwidths); - - /// Provides a direct channel of communication between the object and each of the frame and document windows. - /// A pointer to the IOleInPlaceActiveObject interface on the active in-place object. - /// - /// A pointer to a string containing a name that describes the object an embedding container can use in composing its window - /// title. It can be NULL if the object does not require the container to change its window titles. Containers should - /// ignore this parameter and always use their own name in the title bar. - /// - /// - /// - /// Generally, an embedded object should pass NULL for the pszObjName parameter (see Notes to Implementers below). - /// However, if you are working in conjunction with a container that does display the name of the in-place active object in its - /// title bar, then you should compose a string in the following form: <application name> – <object short-type name>. - /// - /// Notes to Callers - /// - /// IOleInPlaceUIWindow::SetActiveObject is called by the object to establish a direct communication link between itself - /// and the document and frame windows. - /// - /// - /// When deactivating, the object calls IOleInPlaceUIWindow::SetActiveObject, passing NULL for the pActiveObject - /// and pszObjName parameters. - /// - /// - /// An object must call IOleInPlaceUIWindow::SetActiveObject before calling IOleInPlaceFrame::SetMenu to give the - /// container the pointer to the active object. The container then uses this pointer in processing - /// IOleInPlaceFrame::SetMenu and to pass to OleSetMenuDescriptor. - /// - /// Notes to Implementers - /// - /// The Microsoft Windows User Interface Design Guide recommends that an in-place container ignore the pszObjName parameter - /// passed in this method. The guide says "The title bar is not affected by in-place activation. It always displays the - /// top-level container's name." - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplaceuiwindow-setactiveobject HRESULT - // SetActiveObject( IOleInPlaceActiveObject *pActiveObject, LPCOLESTR pszObjName ); - void SetActiveObject([In] IOleInPlaceActiveObject pActiveObject, [MarshalAs(UnmanagedType.LPWStr)] string pszObjName); - } - - /// - /// - /// Enables a linked object to provide its container with functions pertaining to linking. The most important of these functions is - /// binding to the link source, that is, activating the connection to the document that stores the linked object's native data. - /// IOleLink also defines functions for managing information about the linked object, such as the location of the link source - /// and the cached presentation data for the linked object. - /// - /// - /// A container application can distinguish between embedded objects and linked objects by querying for IOleLink; only linked - /// objects implement IOleLink. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nn-oleidl-iolelink - [PInvokeData("oleidl.h", MSDNShortId = "NN:oleidl.IOleLink")] - [ComImport, Guid("0000011d-0000-0000-C000-000000000046"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] - public interface IOleLink - { - /// Specifies how often a linked object should update its cached data. - /// - /// Specifies how often a linked object should update its cached data. The possible values for dwUpdateOpt are taken from - /// the enumeration OLEUPDATE. - /// - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// E_INVALIDARG - /// The supplied value is invalid. - /// - /// - /// - /// - /// Notes to Callers - /// - /// Your container application should call IOleLink::SetUpdateOptions when the end user changes the update option for a - /// linked object. - /// - /// - /// The end user selects the update option for a linked object using the Links dialog box. If you use the OleUIEditLinks - /// function to display this dialog box, you must implement the IOleUILinkContainer interface. The dialog box calls your - /// IOleUILinkContainer::SetLinkUpdateOptions method to specify the update option chosen by the end user. Your implementation of - /// this method should call the IOleLink::SetUpdateOptions method to pass the selected option to the linked object. - /// - /// Notes to Implementers - /// - /// The default update option is OLEUDPATE_ALWAYS. The linked object's implementation of IPersistStorage::Save saves the current - /// update option. - /// - /// - /// If OLEUDPATE_ALWAYS is specified as the update option, the linked object updates the link's caches in the following situations: - /// - /// - /// - /// When the update option is changed from manual to automatic, if the link source is running. - /// - /// - /// Whenever the linked object binds to the link source. - /// - /// - /// - /// Whenever the link source is running and the linked object's IOleObject::Close, IPersistStorage::Save, or IAdviseSink::OnSave - /// implementations are called. - /// - /// - /// - /// - /// For both manual and automatic links, the linked object updates the cache whenever the container application calls - /// IOleObject::Update or IOleLink::Update. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolelink-setupdateoptions HRESULT SetUpdateOptions( [in] - // DWORD dwUpdateOpt ); - [PreserveSig] - HRESULT SetUpdateOptions(OLEUPDATE dwUpdateOpt); - - /// Retrieves a value indicating how often the linked object updates its cached data. - /// - /// A pointer to a variable that receives the current value for the linked object's update option, indicating how often the - /// linked object updates the cached data for the linked object. The possible values for pdwUpdateOpt are taken from the - /// enumeration OLEUPDATE. - /// - /// This method returns S_OK on success. - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolelink-getupdateoptions HRESULT GetUpdateOptions( [out] - // DWORD *pdwUpdateOpt ); - [PreserveSig] - HRESULT GetUpdateOptions(out OLEUPDATE pdwUpdateOpt); - - /// Sets the moniker for the link source. - /// - /// A pointer to the IMoniker interface on a moniker that identifies the new link source of the linked object. A value of - /// NULL breaks the link. - /// - /// - /// The CLSID of the link source that the linked object should use to access information about the linked object when it is not bound. - /// - /// This method returns S_OK on success. - /// - /// Notes to Callers - /// - /// Your container application can call IOleLink::SetSourceMoniker when the end user changes the source of a link or - /// breaks a link. Note that this requires your container to use the MkParseDisplayName function to create a moniker out of the - /// display name that the end user enters. If you'd rather have the linked object perform the parsing, your container can call - /// IOleLink::SetSourceDisplayName instead of IOleLink::SetSourceMoniker. - /// - /// - /// The end user changes the source of a link or breaks a link using the Links dialog box. If you use the OleUIEditLinks - /// function to display the Links dialog box, you must implement the IOleUILinkContainer interface. The dialog box calls - /// your implementations of IOleUILinkContainer::SetLinkSource and IOleUILinkContainer::CancelLink; your implementation of these - /// methods can call IOleLink::SetSourceMoniker. - /// - /// - /// If the linked object is currently bound to its link source, the linked object's implementation of - /// IOleLink::SetSourceMoniker closes the link before changing the moniker. - /// - /// Notes to Implementers - /// - /// The IOleLink contract does not specify how the linked object stores or uses the link source moniker. The provided - /// implementation stores the absolute moniker specified when the link is created or when the moniker is changed; it then - /// computes and stores a relative moniker. Future implementations might manage monikers differently to provide better moniker - /// tracking. The absolute moniker provides the complete path to the link source. The linked object uses this absolute moniker - /// and the moniker of the compound document to compute a relative moniker that identifies the link source relative to the - /// compound document that contains the link. - /// - /// pmkCompoundDoc->RelativePathTo(pmkAbsolute, ppmkRelative) - /// - /// When binding to the link source, the linked object first tries to bind using the relative moniker. If that fails, it tries to - /// bind the absolute moniker. - /// - /// - /// When the linked object successfully binds using either the relative or the absolute moniker, it automatically updates the - /// other moniker. The linked object also updates both monikers when it is bound to the link source and it receives a rename - /// notification through the IAdviseSink::OnRename method. A container application can also use the - /// IOleLink::SetSourceDisplayName method to change a link's moniker. - /// - /// The linked object's implementation of IPersistStorage::Save saves both the relative and the absolute moniker. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolelink-setsourcemoniker HRESULT SetSourceMoniker( [in] - // IMoniker *pmk, [in] REFCLSID rclsid ); - [PreserveSig] - HRESULT SetSourceMoniker([In, Optional] IMoniker pmk, in Guid rclsid); - - /// Retrieves the moniker identifying the link source of a linked object. - /// - /// Address of an IMoniker pointer variable that receives the interface pointer to an absolute moniker that identifies the link - /// source. When successful, the implementation must call AddRef on ppmk; it is the caller's responsibility to call - /// Release. If an error occurs the implementation must set ppmk to NULL. - /// - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// MK_E_UNAVAILABLE - /// No moniker is available. - /// - /// - /// - /// - /// Notes to Callers - /// - /// Your container application can call IOleLink::GetSourceMoniker to display the current source of a link in the - /// Links dialog box. Note that this requires your container to use the IMoniker::GetDisplayName method to get the display - /// name of the moniker. If you would rather get the display name directly, your container can call - /// IOleLink::GetSourceDisplayName instead of IOleLink::GetSourceMoniker. - /// - /// - /// If you use the OleUIEditLinks function to display the Links dialog box, you must implement the IOleUILinkContainer - /// interface. The dialog box calls your implementations of IOleUILinkContainer::GetLinkSource to get the string it should - /// display. Your implementation of that method can call IOleLink::GetSourceMoniker. - /// - /// Notes to Implementers - /// - /// The linked object stores both an absolute and a relative moniker for the link source. If the relative moniker is non- - /// NULL and a moniker is available for the compound document, IOleLink::GetSourceMoniker returns the moniker - /// created by composing the relative moniker onto the end of the compound document's moniker. Otherwise, it returns the absolute - /// moniker or, if an error occurs, NULL. - /// - /// - /// The container specifies the absolute moniker when it calls one of the OleCreateLink functions to create a link. The - /// application can call IOleLink::GetSourceMoniker or IOleLink::GetSourceDisplayName to change the absolute moniker. In - /// addition, the linked object automatically updates the monikers whenever it successfully binds to the link source, or when it - /// is bound to the link source and it receives a rename notification through the IAdviseSink::OnRename method. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolelink-getsourcemoniker HRESULT GetSourceMoniker( [out] - // IMoniker **ppmk ); - [PreserveSig] - HRESULT GetSourceMoniker(out IMoniker ppmk); - - /// Sets the display name for the link source. - /// A pointer to the display name of the new link source. This parameter cannot be NULL. - /// - /// This method returns S_OK on success. - /// Values from MkParseDisplayName may also be returned here. - /// - /// - /// Notes to Callers - /// - /// Your container application can call IOleLink::SetSourceDisplayName when the end user changes the source of a link or - /// breaks a link. Note that this requires the linked object to create a moniker out of the display name. If you'd rather parse - /// the display name into a moniker yourself, your container can call IOleLink::SetSourceMoniker instead of IOleLink::SetSourceDisplayName. - /// - /// - /// If you use the OleUIEditLinks function to display the Links dialog box, you must implement the IOleUILinkContainer - /// interface. The dialog box calls your implementations of IOleUILinkContainer::SetLinkSource and - /// IOleUILinkContainer::CancelLink. Your implementation of these methods can call IOleLink::SetSourceDisplayName. - /// - /// - /// If your container application is immediately going to bind to a newly specified link source, you should call - /// MkParseDisplayName and IOleLink::SetSourceMoniker instead, and then call IOleLink::BindToSource using the bind context from - /// the parsing operation. By reusing the bind context, you can avoid redundant loading of objects that might otherwise occur. - /// - /// Notes to Implementers - /// - /// The contract for IOleLink::SetSourceDisplayName does not specify when the linked object will parse the display name - /// into a moniker. The parsing can occur before IOleLink::SetSourceDisplayName returns, or the linked object can store - /// the display name and parse it only when it needs to bind to the link source. Note that parsing the display name is - /// potentially an expensive operation because it might require binding to the link source. The provided implementation of - /// IOleLink::SetSourceDisplayName parses the display name and then releases the bind context used in the parse operation. - /// This can result in running and then stopping the link source server. - /// - /// - /// If the linked object is bound to the current link source, the implementation of IOleLink::SetSourceDisplayName breaks - /// the connection. - /// - /// For more information on how the linked object stores and uses the moniker to the link source, see IOleLink::SetSourceMoniker. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolelink-setsourcedisplayname HRESULT - // SetSourceDisplayName( [in] LPCOLESTR pszStatusText ); - [PreserveSig] - HRESULT SetSourceDisplayName([MarshalAs(UnmanagedType.LPWStr)] string pszStatusText); - - /// Retrieves the display name of the link source of the linked object. - /// - /// Address of a pointer variable that receives a pointer to the display name of the link source. If an error occurs, - /// ppszDisplayName is set to NULL; otherwise, the implementation must use IMalloc::Alloc to allocate the string - /// returned in ppszDisplayName, and the caller is responsible for calling IMalloc::Free to free it. Both caller and - /// called use the allocator returned by CoGetMalloc. - /// - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// E_FAIL - /// The operation failed. - /// - /// - /// - /// Retrieving the display name requires calling these functions; therefore, this method may return errors generated by - /// CreateBindCtx and IMoniker::GetDisplayName. - /// - /// - /// - /// Notes to Callers - /// Your container application can call IOleLink::GetSourceDisplayName to display the current source of a link. - /// - /// The current source of a link is displayed in the Links dialog box. If you use the OleUIEditLinks function to display - /// the Links dialog box, you must implement the IOleUILinkContainer interface. The dialog box calls your implementations - /// of IOleUILinkContainer::GetLinkSource to get the string it should display. Your implementation of that method can call IOleLink::GetSourceDisplayName. - /// - /// Notes to Implementers - /// - /// The linked object's implementation of IOleLink::GetSourceDisplayName calls IOleLink::GetSourceMoniker to get the link - /// source moniker, and then calls IMoniker::GetDisplayName to get that moniker's display name. This operation is potentially - /// expensive because it might require binding the moniker. All of the system-provided monikers can return a display name without - /// binding, but there is no guarantee that other moniker implementations can. Instead of making repeated calls to - /// IOleLink::GetSourceDisplayName, your container application can cache the name and update it whenever the link source - /// is bound. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolelink-getsourcedisplayname HRESULT - // GetSourceDisplayName( [out] LPOLESTR *ppszDisplayName ); - [PreserveSig] - HRESULT GetSourceDisplayName(out IntPtr ppszDisplayName); - - /// Activates the connection to the link source by binding the moniker stored within the linked object. - /// - /// Specifies how to proceed if the link source has a different CLSID from the last time it was bound. If this parameter is zero - /// and the CLSIDs are different, the method fails and returns OLE_E_CLASSDIFF. If the OLELINKBIND_EVENIFCLASSDIFF value from the - /// OLELINKBIND enumeration is specified and the CLSIDs are different, the method binds successfully and updates the CLSID stored - /// in the linked object. - /// - /// - /// A pointer to the IBindCtx interface on the bind context to be used in this binding operation. This parameter can be - /// NULL. The bind context caches objects bound during the binding process, contains parameters that apply to all - /// operations using the bind context, and provides the means by which the binding implementation should retrieve information - /// about its environment. For more information, see IBindCtx. - /// - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// OLE_E_CLASSDIFF - /// - /// The link source was not bound because its CLSID has changed. This error is returned only if the OLELINKBIND_EVENIFCLASSDIFF - /// flag is not specified in the bindflags parameter. - /// - /// - /// - /// MK_E_NOOBJECT - /// - /// The link source could not be found or (if the link source's moniker is a composite) some intermediate object identified in - /// the composite could not be found. - /// - /// - /// - /// E_UNSPEC - /// The link's moniker is NULL. - /// - /// - /// - /// Binding the moniker might require calling the CreateBindCtx function; therefore, this method may return errors generated by CreateBindCtx. - /// - /// - /// - /// Notes to Callers - /// - /// Typically, your container application does not need to call the IOleLink::BindToSource method directly. When it's - /// necessary to activate the connection to the link source, your container typically calls IOleObject::DoVerb, - /// IOleObject::Update, or IOleLink::Update. The linked object's implementation of these methods calls - /// IOleLink::BindToSource. Your container can also call the OleRun function, which calls IOleLink::BindToSource - /// when called on a linked object. - /// - /// - /// In each of the examples listed previously, in which IOleLink::BindToSource is called indirectly, the bindflags - /// parameter is set to zero. Consequently, these calls can fail with the OLE_E_CLASSDIFF error if the class of the link source - /// is different from what it was the last time the linked object was bound. This could happen, for example, if the original link - /// source was an embedded Lotus spreadsheet that an end user had subsequently converted (using the Change Type dialog box) to an - /// Excel spreadsheet. - /// - /// - /// If you want your container to bind even though the link source now has a different CLSID, you can call - /// IOleLink::BindToSource directly and specify OLELINKBIND_EVENIFCLASSDIFF for the bindflags parameter. This call binds - /// to the link source and updates the link object's CLSID. Alternatively, your container can delete the existing link and use - /// the OleCreateLink function to create a new linked object. - /// - /// Notes to Implementers - /// The linked object caches the interface pointer to the link source acquired during binding. - /// - /// The linked object's IOleLink::BindToSource implementation first tries to bind using a moniker consisting of the - /// compound document's moniker composed with the link source's relative moniker. If successful, it updates the link's absolute - /// moniker. Otherwise, it tries to bind using the absolute moniker, updating the relative moniker if successful. - /// - /// - /// If IOleLink::BindToSource binds to the link source, it calls the compound document's IOleContainer::LockContainer - /// implementation to keep the containing compound document alive while the link source is running. IOleLink::BindToSource - /// also calls the IOleObject::Advise and IDataObject::DAdvise implementations of the link source to set up advisory connections. - /// The IOleLink::UnbindSource implementation unlocks the container and deletes the advisory connections. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolelink-bindtosource HRESULT BindToSource( [in] DWORD - // bindflags, [in] IBindCtx *pbc ); - [PreserveSig] - HRESULT BindToSource(OLELINKBIND bindflags, [In, Optional] IBindCtx pbc); - - /// Activates the connection between the linked object and the link source if the link source is already running. - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// S_FALSE - /// The link source is not running. - /// - /// - /// - /// Binding the moniker might require calling CreateBindCtx, IMoniker::IsRunning, or IOleLink::BindToSource; therefore, errors - /// generated by these functions can also be returned. - /// - /// - /// - /// You typically do not need to call IOleLink::BindIfRunning. This method is primarily called by the linked object. - /// Notes to Implementers - /// - /// The linked object's implementation of IOleLink::BindIfRunning checks the running object table (ROT) to determine - /// whether the link source is already running. It checks both the relative and absolute monikers. If the link source is running, - /// IOleLink::BindIfRunning calls IOleLink::BindToSource to connect the linked object to the link source. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolelink-bindifrunning HRESULT BindIfRunning(); - [PreserveSig] - HRESULT BindIfRunning(); - - /// Retrieves a pointer to the link source if the connection is active. - /// - /// Address of IDataObject pointer variable that receives the interface pointer to the link source. When successful, the - /// implementation must call IUnknown::AddRef on ppunk; it is the caller's responsibility to call IUnknown::Release. If an - /// error occurs, the implementation sets ppunk to NULL. - /// - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// E_FAIL - /// The operation failed. - /// - /// - /// - /// You typically do not need to call IOleLink::GetBoundSource. - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolelink-getboundsource HRESULT GetBoundSource( [out] - // IUnknown **ppunk ); - [PreserveSig] - HRESULT GetBoundSource(out IDataObject ppunk); - - /// Breaks the connection between a linked object and its link source. - /// This method returns S_OK on success. - /// - /// - /// You typically do not call UnbindSource directly. When it's necessary to deactivate the connection to the link source, - /// your container typically calls IOleObject::Close or IUnknown::Release; the linked object's implementation of these methods - /// calls UnbindSource. The linked object's IAdviseSink::OnClose implementation also calls UnbindSource. - /// - /// Notes to Implementers - /// - /// The linked object's implementation of UnbindSource does nothing if the link source is not currently bound. If the link - /// source is bound, UnbindSource calls the link source's IOleObject::Unadvise and IDataObject::DUnadvise implementations - /// to delete the advisory connections to the link source. The UnbindSource method also calls the compound document's - /// IOleContainer::LockContainer implementation to unlock the containing compound document. This undoes the lock on the container - /// and the advisory connections that were established in IOleLink::BindToSource. UnbindSource releases all the linked - /// object's interface pointers to the link source. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolelink-unbindsource HRESULT UnbindSource(); - [PreserveSig] - HRESULT UnbindSource(); - - /// - /// Updates the compound document's cached data for a linked object. This involves binding to the link source, if it is not - /// already bound. - /// - /// - /// A pointer to the IBindCtx interface on the bind context to be used in binding the link source. This parameter can be - /// NULL. The bind context caches objects bound during the binding process, contains parameters that apply to all - /// operations using the bind context, and provides the means by which the binding implementation should retrieve information - /// about its environment. For more information, see IBindCtx. - /// - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// CACHE_E_NOCACHE_UPDATE - /// The bind operation worked but no caches were updated. - /// - /// - /// CACHE_S_SOMECACHES_NOTUPDATED - /// The bind operation worked but not all caches were updated. - /// - /// - /// OLE_E_CANT_BINDTOSOURCE - /// Unable to bind to the link source. - /// - /// - /// - /// - /// Notes to Callers - /// Your container application should call Update if the end user updates the cached data for a linked object. - /// - /// The end user can update the cached data for a linked object by choosing the Update Now button in the Links - /// dialog box. If you use the OleUIEditLinks function to display the Links dialog box, you must implement the - /// IOleUILinkContainer interface. The dialog box calls your implementations of IOleUILinkContainer::UpdateLink when the end user - /// chooses the Update Now button. Your implementation of that method can call Update. - /// - /// - /// Your container application can also call Update to update a linked object, because that method calls Update - /// when it is called on a linked object. - /// - /// - /// This method updates both automatic links and manual links. For manual links, calling Update or Update is the - /// only way to update the caches. For more information on automatic and manual links, see IOleLink::SetUpdateOptions. - /// - /// Notes on Implementation - /// - /// If pbc is non- NULL, the linked object's implementation of Update calls IBindCtx::RegisterObjectBound to - /// register the bound link source. This ensures that the link source remains running until the bind context is released. - /// - /// The current caches are left intact if the link source cannot be bound. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolelink-update HRESULT Update( [in] IBindCtx *pbc ); - [PreserveSig] - HRESULT Update([In, Optional] IBindCtx pbc); - } - - /// - /// Serves as the principal means by which an embedded object provides basic functionality to, and communicates with, its container. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nn-oleidl-ioleobject - [PInvokeData("oleidl.h", MSDNShortId = "58b32c87-39b6-4d64-9174-cf798ed302c2")] - [ComImport, Guid("00000112-0000-0000-C000-000000000046"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] - public interface IOleObject - { - /// Informs an embedded object of its display location, called a "client site," within its container. - /// Pointer to the IOleClientSite interface on the container application's client-site. - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// E_UNEXPECTED - /// An unexpected error occurred. - /// - /// - /// - /// - /// - /// Within a compound document, each embedded object has its own client site — the place where it is displayed and through - /// which it receives information about its storage, user interface, and other resources. IOleObject::SetClientSite is - /// the only method enabling an embedded object to obtain a pointer to its client site. - /// - /// Notes to Callers - /// - /// A container can notify an object of its client site either at the time the object is created or, subsequently, when the - /// object is initialized. - /// - /// - /// When creating or loading an object, a container may pass a client-site pointer (along with other arguments) to one of the - /// following helper functions: OleCreate, OleCreateFromFile, OleCreateFromData or OleLoad. These helper functions load an - /// object handler for the new object and call IOleObject::SetClientSite on the container's behalf before returning a - /// pointer to the new object. - /// - /// - /// Passing a client-site pointer informs the object handler that the client site is ready to process requests. If the client - /// site is unlikely to be ready immediately after the handler is loaded, you may want your container to pass a NULL - /// client-site pointer to the helper function. The NULL pointer says that no client site is available and thereby defers - /// notifying the object handler of the client site until the object is initialized. In response, the helper function returns a - /// pointer to the object, but upon receiving that pointer the container must call IOleObject::SetClientSite as part of - /// initializing the new object. - /// - /// Notes to Implementers - /// Implementation consists simply of incrementing the reference count on, and storing, the pointer to the client site. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleobject-setclientsite HRESULT SetClientSite( - // IOleClientSite *pClientSite ); - [PreserveSig] - HRESULT SetClientSite(IOleClientSite pClientSite); - - /// Retrieves a pointer to an embedded object's client site. - /// - /// Address of IOleClientSite pointer variable that receives the interface pointer to the object's client site. If an object - /// does not yet know its client site, or if an error has occurred, ppClientSite must be set to NULL. Each time an object - /// receives a call to IOleObject::GetClientSite, it must increase the reference count on ppClientSite. It is the - /// caller's responsibility to call Release when it is done with ppClientSite. - /// - /// This method returns S_OK on success. - /// - /// - /// Link clients most commonly call the IOleObject::GetClientSite method in conjunction with the - /// IOleClientSite::GetContainer method to traverse a hierarchy of nested objects. A link client calls - /// IOleObject::GetClientSite to get a pointer to the link source's client site. The client then calls - /// IOleClientSite::GetContainer to get a pointer to the link source's container. Finally, the client calls - /// QueryInterface to get IOleObject and IOleObject::GetClientSite to get the container's client site within its - /// container. By repeating this sequence of calls, the caller can eventually retrieve a pointer to the master container in - /// which all the other objects are nested. - /// - /// Notes to Callers - /// - /// The returned client-site pointer will be NULL if an embedded object has not yet been informed of its client site. - /// This will be the case with a newly loaded or created object when a container has passed a NULL client-site pointer to - /// one of the object-creation helper functions but has not yet called IOleObject::SetClientSite as part of initializing the object. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleobject-getclientsite HRESULT GetClientSite( - // IOleClientSite **ppClientSite ); - [PreserveSig] - HRESULT GetClientSite(out IOleClientSite ppClientSite); - - /// Provides an object with the names of its container application and the compound document in which it is embedded. - /// Pointer to the name of the container application in which the object is running. - /// - /// Pointer to the name of the compound document that contains the object. If you do not wish to display the name of the - /// compound document, you can set this parameter to NULL. - /// - /// This method returns S_OK on success. - /// - /// Notes for Callers - /// - /// Call IOleObject::SetHostNames only for embedded objects, because for linked objects, the link source provides its own - /// separate editing window and title bar information. - /// - /// Notes to Implementers - /// - /// An object's application of IOleObject::SetHostNames should include whatever modifications to its user interface may - /// be appropriate to an object's embedded state. Such modifications typically will include adding and removing menu commands - /// and altering the text displayed in the title bar of the editing window. - /// - /// - /// The complete window title for an embedded object in an SDI container application or an MDI application with a maximized - /// child window should appear as follows: - /// - /// Otherwise, the title should be: - /// - /// The "object short type" refers to a form of an object's name short enough to be displayed in full in a list box. Because - /// these identifying strings are not stored as part of the persistent state of the object, IOleObject::SetHostNames must - /// be called each time the object loads or runs. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleobject-sethostnames HRESULT SetHostNames( LPCOLESTR - // szContainerApp, LPCOLESTR szContainerObj ); - [PreserveSig] - HRESULT SetHostNames([MarshalAs(UnmanagedType.LPWStr)] string szContainerApp, [MarshalAs(UnmanagedType.LPWStr)] string szContainerObj); - - /// Changes an embedded object from the running to the loaded state. Disconnects a linked object from its link source. - /// - /// - /// Indicates whether the object is to be saved as part of the transition to the loaded state. Valid values are taken from the - /// enumeration OLECLOSE. - /// - /// - /// Note The OLE 2 user model recommends that object applications do not prompt users before saving linked or embedded - /// objects, including those activated in place. This policy represents a change from the OLE 1 user model, in which object - /// applications always prompt the user to decide whether to save changes. - /// - /// - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// OLE_E_PROMPTSAVECANCELLED - /// The user was prompted to save but chose the Cancel button from the prompt message box. - /// - /// - /// - /// - /// Notes to Callers - /// - /// A container application calls IOleObject::Close when it wants to move the object from a running to a loaded state. - /// Following such a call, the object still appears in its container but is not open for editing. Calling - /// IOleObject::Close on an object that is loaded but not running has no effect. Closing a linked object simply means - /// disconnecting it. - /// - /// Notes to Implementers - /// Upon receiving a call to IOleObject::Close, a running object should do the following: - /// - /// - /// - /// If the object has been changed since it was last opened for editing, it should request to be saved, or not, according to - /// instructions specified in dwSaveOption. If the option is to save the object, then it should call its container's - /// IOleClientSite::SaveObject interface. - /// - /// - /// - /// - /// If the object has IDataObject::DAdvise connections with ADVF_DATAONSTOP flags, then it should send an - /// IAdviseSink::OnDataChange notification. See IDataObject::DAdvise for details. - /// - /// - /// - /// If the object currently owns the Clipboard, it should empty it by calling OleFlushClipboard. - /// - /// - /// - /// If the object is currently visible, notify its container by calling IOleClientSite::OnShowWindow with the fshow argument set - /// to FALSE. - /// - /// - /// - /// Send IAdviseSink::OnClose notifications to appropriate advise sinks. - /// - /// - /// Finally, forcibly cut off all remoting clients by calling CoDisconnectObject. - /// - /// - /// - /// If the object application is a local server (an EXE rather than a DLL), closing the object should also shut down the object - /// application unless the latter is supporting other running objects or has another reason to remain in the running state. Such - /// reasons might include the presence of IClassFactory::LockServer locks, end-user control of the application, or the existence - /// of other open documents requiring access to the application. - /// - /// - /// Calling IOleObject::Close on a linked object disconnects it from, but does not shut down, its source application. A - /// source application that is visible to the user when the object is closed remains visible and running after the disconnection - /// and does not send an IAdviseSink::OnClose notification to the link container. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleobject-close HRESULT Close( DWORD dwSaveOption ); - [PreserveSig] - HRESULT Close(OLECLOSE dwSaveOption); - - /// - /// Notifies an object of its container's moniker, the object's own moniker relative to the container, or the object's full moniker. - /// - /// The moniker is passed in pmk. Possible values are from the enumeration OLEWHICHMK. - /// Pointer to where to return the moniker. - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// E_FAIL - /// The operation failed. - /// - /// - /// - /// - /// - /// A container that supports links to embedded objects must be able to inform an embedded object when its moniker has changed. - /// Otherwise, subsequent attempts by link clients to bind to the object will fail. The IOleObject::SetMoniker method - /// provides one way for a container to communicate this information. - /// - /// - /// The container can pass either its own moniker, an object's moniker relative to the container, or an object's full moniker. - /// In practice, if a container passes anything other than an object's full moniker, each object calls the container back to - /// request assignment of the full moniker, which the object requires to register itself in the running object table. - /// - /// - /// The moniker of an object relative to its container is stored by the object handler as part of the object's persistent state. - /// The moniker of the object's container, however, must not be persistently stored inside the object because the container can - /// be renamed at any time. - /// - /// Notes to Callers - /// - /// A container calls IOleObject::SetMoniker when the container has been renamed, and the container's embedded objects - /// currently or can potentially serve as link sources. Containers call SetMoniker mainly in the context of linking because an - /// embedded object is already aware of its moniker. Even in the context of linking, calling this method is optional because - /// objects can call IOleClientSite::GetMoniker to force assignment of a new moniker. - /// - /// Notes to Implementers - /// - /// Upon receiving a call to IOleObject::SetMoniker, an object should register its full moniker in the running object - /// table and send IAdviseSink::OnRename notification to all advise sinks that exist for the object. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleobject-setmoniker HRESULT SetMoniker( DWORD - // dwWhichMoniker, IMoniker *pmk ); - [PreserveSig] - HRESULT SetMoniker(OLEWHICHMK dwWhichMoniker, IMoniker pmk); - - /// Retrieves an embedded object's moniker, which the caller can use to link to the object. - /// - /// - /// Determines how the moniker is assigned to the object. Depending on the value of dwAssign, IOleObject::GetMoniker does - /// one of the following: - /// - /// - /// - /// Obtains a moniker only if one has already been assigned. - /// - /// - /// Forces assignment of a moniker, if necessary, in order to satisfy the call. - /// - /// - /// Obtains a temporary moniker. - /// - /// - /// Values for - /// dwAssign - /// are specified in the enumeration - /// OLEGETMONIKER - /// . - /// - /// Note You cannot pass OLEGETMONIKER_UNASSIGN when calling IOleObject::GetMoniker. This value is valid only when - /// calling IOleObject::GetMoniker. - /// - /// - /// - /// Specifies the form of the moniker being requested. Possible values are taken from the enumeration OLEWHICHMK. - /// - /// - /// Address of IMoniker pointer variable that receives the interface pointer to the object's moniker. If an error occurs, ppmk - /// must be set to NULL. Each time an object receives a call to IOleObject::GetMoniker, it must increase the - /// reference count on ppmk. It is the caller's responsibility to call Release when it is done with ppmk. - /// - /// This method returns S_OK on success. - /// - /// The IOleObject::GetMoniker method returns an object's moniker. Like IOleObject::SetMoniker, this method is important - /// only in the context of managing links to embedded objects and even in that case is optional. A potential link client that - /// requires an object's moniker to bind to the object can call this method to obtain that moniker. The default implementation - /// of IOleObject::GetMoniker calls the IOleClientSite::GetMoniker, returning E_UNEXPECTED if the object is not running - /// or does not have a valid pointer to a client site. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleobject-getmoniker HRESULT GetMoniker( DWORD dwAssign, - // DWORD dwWhichMoniker, IMoniker **ppmk ); - [PreserveSig] - HRESULT GetMoniker(OLEGETMONIKER dwAssign, OLEWHICHMK dwWhichMoniker, out IMoniker ppmk); - - /// - /// Initializes a newly created object with data from a specified data object, which can reside either in the same container or - /// on the Clipboard. - /// - /// - /// Pointer to the IDataObject interface on the data object from which the initialization data is to be obtained. This parameter - /// can be NULL, which indicates that the caller wants to know if it is worthwhile trying to send data; that is, whether - /// the container is capable of initializing an object from data passed to it. The data object to be passed can be based on - /// either the current selection within the container document or on data transferred to the container from an external source. - /// - /// - /// TRUE indicates the container is inserting a new object inside itself and initializing that object with data from the - /// current selection; FALSE indicates a more general programmatic data transfer, most likely from a source other than - /// the current selection. - /// - /// This parameter is reserved and must be zero. - /// - /// - /// This method returns S_OK if pDataObject is not NULL, the object successfully attempted to initialize itself from the - /// provided data; if pDataObject is NULL, the object is able to attempt a successful initialization.. Other possible - /// return values include the following. - /// - /// - /// - /// Return code - /// Description - /// - /// - /// S_FALSE - /// - /// If pDataObject is not NULL, the object made no attempt to initialize itself; if pDataObject is NULL, the object cannot - /// attempt to initialize itself from the data provided. - /// - /// - /// - /// E_NOTIMPL - /// The object does not support InitFromData. - /// - /// - /// OLE_E_NOTRUNNING - /// The object is not running and therefore cannot perform the operation. - /// - /// - /// - /// - /// - /// This method enables a container document to insert within itself a new object whose content is based on a current data - /// selection within the container. For example, a spreadsheet document may want to create a graph object based on data in a - /// selected range of cells. - /// - /// - /// Using this method, a container can also replace the contents of an embedded object with data transferred from another - /// source. This provides a convenient way of updating an embedded object. - /// - /// Notes to Callers - /// - /// Following initialization, the container should call IOleObject::GetMiscStatus to check the value of the - /// OLEMISC_INSERTNOTREPLACE bit. If the bit is on, the new object inserts itself following the selected data. If the bit is - /// off, the new object replaces the selected data. - /// - /// Notes to Implementers - /// - /// A container specifies whether to base a new object on the current selection by passing either TRUE or FALSE to - /// the fCreation parameter. - /// - /// - /// If fCreation is TRUE, the container is attempting to create a new instance of an object, initializing it with the - /// selected data specified by the data object. - /// - /// - /// If fCreation is FALSE, the caller is attempting to replace the object's current contents with that pointed to by - /// pDataObject. The usual constraints that apply to an object during a paste operation should be applied here. For example, if - /// the type of the data provided is unacceptable, the object should fail to initialize and return S_FALSE. - /// - /// If the object returns S_FALSE, it cannot initialize itself from the provided data. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleobject-initfromdata HRESULT InitFromData( IDataObject - // *pDataObject, BOOL fCreation, DWORD dwReserved ); - [PreserveSig] - HRESULT InitFromData(IDataObject pDataObject, [MarshalAs(UnmanagedType.Bool)] bool fCreation, uint dwReserved = 0); - - /// - /// Retrieves a data object containing the current contents of the embedded object on which this method is called. Using the - /// pointer to this data object, it is possible to create a new embedded object with the same data as the original. - /// - /// This parameter is reserved and must be zero. - /// - /// Address of IDataObject pointer variable that receives the interface pointer to the data object. If an error occurs, - /// ppDataObject must be set to NULL. Each time an object receives a call to IOleObject::GetClipboardData, it must - /// increase the reference count on ppDataObject. It is the caller's responsibility to call Release when it is done with ppDataObject. - /// - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// E_NOTIMPL - /// GetClipboardData is not supported. - /// - /// - /// OLE_E_NOTRUNNING - /// The object is not running. - /// - /// - /// - /// - /// - /// You can use the IOleObject::GetClipboardData method to convert a linked object to an embedded object, in which case - /// the container application would call IOleObject::GetClipboardData and then pass the data received to - /// OleCreateFromData. This method returns a pointer to a data object that is identical to what would have been passed to the - /// clipboard by a standard copy operation. - /// - /// Notes to Callers - /// - /// If you want a stable snapshot of the current contents of an embedded object, call IOleObject::GetClipboardData. - /// Should the data change, you will need to call the function again for an updated snapshot. If you want the caller to be - /// informed of changes that occur to the data, call QueryInterface, then call IDataObject::DAdvise. - /// - /// Notes to Implementers - /// If you implement this function, you must return an IDataObject pointer for an object whose data will not change. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleobject-getclipboarddata HRESULT GetClipboardData( - // DWORD dwReserved, IDataObject **ppDataObject ); - [PreserveSig] - HRESULT GetClipboardData([Optional] uint dwReserved, out IDataObject ppDataObject); - - /// - /// Requests that an object perform an action in response to an end-user's action. The possible actions are enumerated for the - /// object in IOleObject::EnumVerbs. - /// - /// Number assigned to the verb in the OLEVERB structure returned by IOleObject::EnumVerbs. - /// - /// Pointer to the MSG structure describing the event (such as a double-click) that invoked the verb. The caller should pass the - /// MSG structure unmodified, without attempting to interpret or alter the values of any of the structure members. - /// - /// - /// Pointer to the IOleClientSite interface on the object's active client site, where the event occurred that invoked the verb. - /// - /// This parameter is reserved and must be zero. - /// - /// Handle of the document window containing the object. This and lprcPosRect together make it possible to open a temporary - /// window for an object, where hwndParent is the parent window in which the object's window is to be displayed, and lprcPosRect - /// defines the area available for displaying the object window within that parent. A temporary window is useful, for example, - /// to a multimedia object that opens itself for playback but not for editing. - /// - /// - /// Pointer to the RECT structure containing the coordinates, in pixels, that define an object's bounding rectangle in - /// hwndParent. This and hwndParent together enable opening multimedia objects for playback but not for editing. - /// - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// OLE_E_NOT_INPLACEACTIVE - /// iVerb set to OLEIVERB_UIACTIVATE or OLEIVERB_INPLACEACTIVATE and object is not already visible. - /// - /// - /// OLE_E_CANT_BINDTOSOURCE - /// The object handler or link object cannot connect to the link source. - /// - /// - /// DV_E_LINDEX - /// Invalid lindex. - /// - /// - /// OLEOBJ_S_CANNOT_DOVERB_NOW - /// The verb is valid, but in the object's current state it cannot carry out the corresponding action. - /// - /// - /// OLEOBJ_S_INVALIDHWND - /// DoVerb was successful but hwndParent is invalid. - /// - /// - /// OLEOBJ_E_NOVERBS - /// The object does not support any verbs. - /// - /// - /// OLEOBJ_S_INVALIDVERB - /// Link source is across a network that is not connected to a drive on this computer. - /// - /// - /// MK_E_CONNECT - /// Link source is across a network that is not connected to a drive on this computer. - /// - /// - /// OLE_E_CLASSDIFF - /// Class for source of link has undergone a conversion. - /// - /// - /// E_NOTIMPL - /// Object does not support in-place activation or does not recognize a negative verb number. - /// - /// - /// - /// - /// - /// A "verb" is an action that an OLE object takes in response to a message from its container. An object's container, or a - /// client linked to the object, normally calls IOleObject::DoVerb in response to some end-user action, such as - /// double-clicking on the object. The various actions that are available for a given object are enumerated in an OLEVERB - /// structure, which the container obtains by calling IOleObject::EnumVerbs. IOleObject::DoVerb matches the value of - /// iVerb against the iVerb member of the structure to determine which verb to invoke. - /// - /// - /// Through IOleObject::EnumVerbs, an object, rather than its container, determines which verbs (i.e., actions) it supports. OLE - /// 2 defines seven verbs that are available, but not necessarily useful, to all objects. In addition, each object can define - /// additional verbs that are unique to it. The following table describes the verbs defined by OLE. - /// - /// - /// - /// Verb - /// Description - /// - /// - /// OLEIVERB_PRIMARY (0L) - /// - /// Specifies the action that occurs when an end user double-clicks the object in its container. The object, not the container, - /// determines this action. If the object supports in-place activation, the primary verb usually activates the object in place. - /// - /// - /// - /// OLEIVERB_SHOW (-1) - /// - /// Instructs an object to show itself for editing or viewing. Called to display newly inserted objects for initial editing and - /// to show link sources. Usually an alias for some other object-defined verb. - /// - /// - /// - /// OLEIVERB_OPEN (-2) - /// - /// Instructs an object, including one that otherwise supports in-place activation, to open itself for editing in a window - /// separate from that of its container. If the object does not support in-place activation, this verb has the same semantics as OLEIVERB_SHOW. - /// - /// - /// - /// OLEIVERB_HIDE (-3) - /// Causes an object to remove its user interface from the view. Applies only to objects that are activated in-place. - /// - /// - /// OLEIVERB_UIACTIVATE (-4) - /// - /// Activates an object in place, along with its full set of user-interface tools, including menus, toolbars, and its name in - /// the title bar of the container window. If the object does not support in-place activation, it should return E_NOTIMPL. - /// - /// - /// - /// OLEIVERB_INPLACEACTIVATE (-5) - /// - /// Activates an object in place without displaying tools, such as menus and toolbars, that end users need to change the - /// behavior or appearance of the object. Single-clicking such an object causes it to negotiate the display of its - /// user-interface tools with its container. If the container refuses, the object remains active but without its tools displayed. - /// - /// - /// - /// OLEIVERB_DISCARDUNDOSTATE (-6) - /// Used to tell objects to discard any undo state that they may be maintaining without deactivating the object. - /// - /// - /// Notes to Callers - /// - /// Containers call IOleObject::DoVerb as part of initializing a newly created object. Before making the call, containers - /// should first call IOleObject::SetClientSite to inform the object of its display location and IOleObject::SetHostNames to - /// alert the object that it is an embedded object and to trigger appropriate changes to the user interface of the object - /// application in preparation for opening an editing window. - /// - /// - /// IOleObject::DoVerb automatically runs the OLE server application. If an error occurs during verb execution, the - /// object application is shut down. - /// - /// - /// If an end user invokes a verb by some means other than selecting a command from a menu (say, by double-clicking or, more - /// rarely, single-clicking an object), the object's container should pass a pointer to a Windows MSG structure containing the - /// appropriate message. For example, if the end user invokes a verb by double-clicking the object, the container should pass a - /// MSG structure containing WM_LBUTTONDBLCLK, WM_MBUTTONDBLCLK, or WM_RBUTTONDBLCLK. If the container passes no message, - /// lpmsg should be set to NULL. The object should ignore the hwnd member of the passed MSG structure, but - /// can use all the other MSG members. - /// - /// - /// If the object's embedding container calls IOleObject::DoVerb, the client-site pointer (pClientSite) passed to - /// IOleObject::DoVerb is the same as that of the embedding site. If the embedded object is a link source, the pointer - /// passed to IOleObject::DoVerb is that of the linking client's client site. - /// - /// - /// When IOleObject::DoVerb is invoked on an OLE link, it may return OLE_E_CLASSDIFF or MK_CONNECTMANUALLY. The link - /// object returns the former error when the link source has been subjected to some sort of conversion while the link was - /// passive. The link object returns the latter error when the link source is located on a network drive that is not currently - /// connected to the caller's computer. The only way to connect a link under these conditions is to first call - /// IUnknown::QueryInterface, ask for IOleLink, allocate a bind context, and run the link source by calling IOleLink::BindToSource. - /// - /// - /// Container applications that do not support general in-place activation can still use the hwndParent and lprcPosRect - /// parameters to support in-place playback of multimedia files. Containers must pass valid hwndParent and lprcPosRect - /// parameters to IOleObject::DoVerb. - /// - /// - /// Some code samples pass a lindex value of -1 instead of zero. The value -1 works but should be avoided in favor of zero. The - /// lindex parameter is a reserved parameter, and for reasons of consistency Microsoft recommends assigning a zero value to all - /// reserved parameters. - /// - /// Notes to Implementers - /// - /// In addition to the above verbs, an object can define in its OLEVERB structure additional verbs that are specific to itself. - /// Positive numbers designate these object-specific verbs. An object should treat any unknown positive verb number as if it - /// were the primary verb and return OLEOBJ_S_INVALIDVERB to the calling function. The object should ignore verbs with negative - /// numbers that it does not recognize and return E_NOTIMPL. - /// - /// - /// If the verb being executed places the object in the running state, you should register the object in the running object - /// table (ROT) even if its server application doesn't support linking. Registration is important because the object at some - /// point may serve as the source of a link in a container that supports links to embeddings. Registering the object with the - /// ROT enables the link client to get a pointer to the object directly, instead of having to go through the object's container. - /// To perform the registration, call IOleClientSite::GetMoniker to get the full moniker of the object, call the - /// GetRunningObjectTable function to get a pointer to the ROT, and then call IRunningObjectTable::Register. - /// - /// - /// Note When the object leaves the running state, remember to revoke the object's registration with the ROT by calling - /// IOleObject::Close. If the object's container document is renamed while the object is running, you should revoke the object's - /// registration and re-register it with the ROT, using its new name. The container should inform the object of its new moniker - /// either by calling IOleObject::SetMoniker or by responding to the object's calling IOleClientSite::GetMoniker. - /// - /// - /// When showing a window as a result of IOleObject::DoVerb, it is very important for the object to explicitly call - /// SetForegroundWindow on its editing window. This ensures that the object's window will be visible to the user even if another - /// process originally obscured it. For more information see SetForegroundWindow and SetActiveWindow. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleobject-doverb HRESULT DoVerb( LONG iVerb, LPMSG - // lpmsg, IOleClientSite *pActiveSite, LONG lindex, HWND hwndParent, LPCRECT lprcPosRect ); - [PreserveSig] - HRESULT DoVerb(int iVerb, in MSG lpmsg, IOleClientSite pActiveSite, [Optional] int lindex, HWND hwndParent, in RECT lprcPosRect); - - /// Exposes a pull-down menu listing the verbs available for an object in ascending order by verb number. - /// - /// Address of IEnumOLEVERB pointer variable that receives the interface pointer to the new enumerator object. Each time an - /// object receives a call to IOleObject::EnumVerbs, it must increase the reference count on ppEnumOleVerb. It is the caller's - /// responsibility to call IUnknown::Release when it is done with ppEnumOleVerb. If an error occurs, ppEnumOleVerb must be set - /// to NULL. - /// - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// OLE_S_USEREG - /// Delegate to the default handler to use the entries in the registry to provide the enumeration. - /// - /// - /// OLEOBJ_E_NOVERBS - /// The object does not support any verbs. - /// - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleobject-enumverbs HRESULT EnumVerbs( IEnumOLEVERB - // **ppEnumOleVerb ); - [PreserveSig] - HRESULT EnumVerbs(out IEnumOLEVERB ppEnumOleVerb); - - /// Updates an object handler's or link object's data or view caches. - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// E_FAIL - /// The operation failed. - /// - /// - /// OLE_E_CANT_BINDTOSOURCE - /// Cannot run object to get updated data. The object is for some reason unavailable to the caller. - /// - /// - /// CACHE_E_NOCACHE_UPDATED - /// No caches were updated. - /// - /// - /// CACHE_S_SOMECACHES_NOTUPDATED - /// Some caches were not updated. - /// - /// - /// - /// - /// - /// The Update method provides a way for containers to keep data updated in their linked and embedded objects. A link - /// object can become out-of-date if the link source has been updated. An embedded object that contains links to other objects - /// can also become out of date. An embedded object that does not contain links cannot become out of date because its data is - /// not linked to another source. - /// - /// Notes to Implementers - /// - /// When a container calls a link object's IOleObject::Update method, the link object finds the link source and gets a - /// new presentation from it. This process may also involve running one or more object applications, which could be time-consuming. - /// - /// - /// When a container calls an embedded object's IOleObject::Update method, it is requesting the object to update all link - /// objects it may contain. In response, the object handler recursively calls IOleObject::Update for each of its own - /// linked objects, running each one as needed. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleobject-update HRESULT Update( ); - [PreserveSig] - HRESULT Update(); - - /// Checks whether an object is up to date. - /// - /// - /// This method returns S_OK if the object is up to date; otherwise, S_FALSE. Other possible return values include the following. - /// - /// - /// - /// Return code - /// Description - /// - /// - /// OLE_E_UNAVAILABLE - /// The status of object cannot be determined in a timely manner. - /// - /// - /// - /// - /// - /// The IOleObject::IsUpToDate method provides a way for containers to check recursively whether all objects are up to - /// date. That is, when the container calls this method on the first object, the object in turn calls it for all its own - /// objects, and they in turn for all of theirs, until all objects have been checked. - /// - /// Notes to Implementers - /// - /// Because of the recursive nature of IOleObject::IsUpToDate, determining whether an object is out-of-date, particularly - /// one containing one or more other objects, can be as time-consuming as simply updating the object in the first place. If you - /// would rather avoid lengthy queries of this type, make sure that IOleObject::IsUpToDate returns OLE_E_UNAVAILABLE. In - /// cases where the object to be queried is small and contains no objects itself, thereby making an efficient query possible, - /// this method can return either S_OK or S_FALSE. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleobject-isuptodate HRESULT IsUpToDate( ); - [PreserveSig] - HRESULT IsUpToDate(); - - /// - /// Retrieves an object's class identifier, the CLSID corresponding to the string identifying the object to an end user. - /// - /// - /// Pointer to the class identifier (CLSID) to be returned. An object's CLSID is the binary equivalent of the user-type name - /// returned by IOleObject::GetUserType. - /// - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// E_FAIL - /// The operation failed. - /// - /// - /// - /// - /// IOleObject::GetUserClassID returns the CLSID associated with the object in the registration database. Normally, this - /// value is identical to the CLSID stored with the object, which is returned by IPersist::GetClassID. For linked objects, this - /// is the CLSID of the last bound link source. If the object is running in an application different from the one in which it - /// was created and for the purpose of being edited is emulating a class that the container application recognizes, the CLSID - /// returned will be that of the class being emulated rather than that of the object's own class. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleobject-getuserclassid HRESULT GetUserClassID( CLSID - // *pClsid ); - [PreserveSig] - HRESULT GetUserClassID(out Guid pClsid); - - /// - /// Retrieves the user-type name of an object for display in user-interface elements such as menus, list boxes, and dialog boxes. - /// - /// - /// The form of the user-type name to be presented to users. Possible values are obtained from the USERCLASSTYPE enumeration. - /// - /// - /// Address of LPOLESTR pointer variable that receives a pointer to the user type string. The caller must free pszUserType using - /// the current IMalloc instance. If an error occurs, the implementation must set pszUserType to NULL. - /// - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// OLE_S_USEREG - /// Delegate to the default handler's implementation using the registry to provide the requested information. - /// - /// - /// - /// - /// - /// Containers call IOleObject::GetUserType in order to represent embedded objects in list boxes, menus, and dialog boxes - /// by their normal, user-recognizable names. Examples include "Word Document," "Excel Chart," and "Paintbrush Object." The - /// information returned by IOleObject::GetUserType is the user-readable equivalent of the binary class identifier - /// returned by IOleObject::GetUserClassID. - /// - /// Notes to Callers - /// - /// The default handler's implementation of IOleObject::GetUserType uses the object's class identifier (the pClsid - /// parameter returned by IOleObject::GetUserClassID) and the dwFormOfType parameter together as a key into the registry. If an - /// entry is found that matches the key exactly, then the user type specified by that entry is returned. If only the CLSID part - /// of the key matches, then the lowest-numbered entry available (usually the full name) is used. If the CLSID is not found, or - /// there are no user types registered for the class, the user type currently found in the object's storage is used. - /// - /// - /// You should not cache the string returned from IOleObject::GetUserType. Instead, call this method each and every time - /// the string is needed. This guarantees correct results when the embedded object is being converted from one type into another - /// without the caller's knowledge. Calling this method is inexpensive because the default handler implements it using the registry. - /// - /// Notes to Implementers - /// - /// You can use the implementation provided by the default handler by returning OLE_S_USEREG as your application's - /// implementation of this method. If the user type name is an empty string, the message "Unknown Object" is returned. - /// - /// You can call the OLE helper function OleRegGetUserType to return the appropriate user type. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleobject-getusertype HRESULT GetUserType( DWORD - // dwFormOfType, LPOLESTR *pszUserType ); - [return: MarshalAs(UnmanagedType.LPWStr)] - [PreserveSig] - HRESULT GetUserType(USERCLASSTYPE dwFormOfType, [MarshalAs(UnmanagedType.LPWStr)] out string pszUserType); - - /// Informs an object of how much display space its container has assigned it. - /// - /// DWORD that describes which form, or "aspect," of an object is to be displayed. The object's container obtains this value - /// from the enumeration DVASPECT (refer to the FORMATETC enumeration). The most common aspect is DVASPECT_CONTENT, which - /// specifies a full rendering of the object within its container. An object can also be rendered as an icon, a thumbnail - /// version for display in a browsing tool, or a print version, which displays the object as it would be rendered using the - /// File Print command. - /// - /// Pointer to the size limit for the object. - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// E_FAIL - /// The operation failed. - /// - /// - /// OLE_E_NOTRUNNING - /// The object is not running. - /// - /// - /// - /// - /// - /// A container calls IOleObject::SetExtent when it needs to dictate to an embedded object the size at which it will be - /// displayed. Often, this call occurs in response to an end user resizing the object window. Upon receiving the call, the - /// object, if possible, should recompose itself gracefully to fit the new window. - /// - /// - /// Whenever possible, a container seeks to display an object at its finest resolution, sometimes called the object's native - /// size. All objects, however, have a default display size specified by their applications, and in the absence of other - /// constraints, this is the size they will use to display themselves. Since an object knows its optimum display size better - /// than does its container, the latter normally requests that size from a running object by calling - /// IOleObject::SetExtent. Only in cases where the container cannot accommodate the value returned by the object does it - /// override the object's preference by calling IOleObject::SetExtent. - /// - /// Notes to Callers - /// - /// You can call IOleObject::SetExtent on an object only when the object is running. If a container resizes an object - /// while an object is not running, the container should keep track of the object's new size but defer calling - /// IOleObject::SetExtent until a user activates the object. If the OLEMISC_RECOMPOSEONRESIZE bit is set on an object, - /// its container should force the object to run before calling IOleObject::SetExtent. - /// - /// - /// As noted above, a container may want to delegate responsibility for setting the size of an object's display site to the - /// object itself, by calling IOleObject::SetExtent. - /// - /// Notes to Implementers - /// - /// You may want to implement this method so that your object rescales itself to match as closely as possible the maximum space - /// available to it in its container. - /// - /// - /// If an object's size is fixed, that is, if it cannot be set by its container, IOleObject::SetExtent should return - /// E_FAIL. This is always the case with linked objects, whose sizes are set by their link sources, not by their containers. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleobject-setextent HRESULT SetExtent( DWORD - // dwDrawAspect, SIZEL *psizel ); - [PreserveSig] - HRESULT SetExtent(DVASPECT dwDrawAspect, in SIZE psizel); - - /// Retrieves a running object's current display size. - /// - /// The aspect of the object whose limit is to be retrieved; the value is obtained from the enumerations DVASPECT and from - /// DVASPECT2. Note that newer objects and containers that support optimized drawing interfaces support the DVASPECT2 - /// enumeration values. Older objects and containers that do not support optimized drawing interfaces may not support - /// DVASPECT2. The most common value for this method is DVASPECT_CONTENT, which specifies a full rendering of the object - /// within its container. - /// - /// Pointer to where the object's size is to be returned. - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// E_INVALIDARG - /// The supplied dwDrawAspect value is invalid. - /// - /// - /// - /// - /// - /// A container calls IOleObject::GetExtent on a running object to retrieve its current display size. If the container - /// can accommodate that size, it will normally do so because the object, after all, knows what size it should be better than - /// the container does. A container normally makes this call as part of initializing an object. - /// - /// - /// The display size returned by IOleObject::GetExtent may differ from the size last set by IOleObject::SetExtent because - /// the latter method dictates the object's display space at the time the method is called but does not necessarily change the - /// object's native size, as determined by its application. - /// - /// - /// If one of the new aspects is requested in dwAspect, this method can either fail or return the same rectangle as for the - /// DVASPECT_CONTENT aspect. - /// - /// - /// Note This method must return the same size as DVASPECT_CONTENT for all the new aspects in DVASPECT2. - /// IViewObject2::GetExtent must do the same thing. - /// - /// Notes to Callers - /// - /// Because a container can make this call only to a running object, the container must instead call IViewObject2::GetExtent if - /// it wants to get the display size of a loaded object from its cache. - /// - /// Notes to Implementers - /// Implementation consists of filling the sizel structure with an object's height and width. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleobject-getextent HRESULT GetExtent( DWORD - // dwDrawAspect, SIZEL *psizel ); - [PreserveSig] - HRESULT GetExtent(DVASPECT dwDrawAspect, out SIZE psizel); - - /// - /// Establishes an advisory connection between a compound document object and the calling object's advise sink, through which - /// the calling object receives notification when the compound document object is renamed, saved, or closed. - /// - /// Pointer to the IAdviseSink interface on the advise sink of the calling object. - /// Pointer to a token that can be passed to IOleObject::Unadvise to delete the advisory connection. - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// E_OUTOFMEMORY - /// Insufficient memory available for this operation. - /// - /// - /// - /// - /// - /// The IOleObject::Advise method sets up an advisory connection between an object and its container, through which the - /// object informs the container's advise sink of close, save, rename, and link-source change events in the object. A container - /// calls this method, normally as part of initializing an object, to register its advisory sink with the object. In return, the - /// object sends the container compound-document notifications by calling IAdviseSink or IAdviseSink2. - /// - /// - /// If container and object successfully establish an advisory connection, the object receiving the call returns a nonzero value - /// through pdwConnection to the container. If the attempt to establish an advisory connection fails, the object returns zero. - /// To delete an advisory connection, the container calls IOleObject::Unadvise and passes this nonzero token back to the object. - /// - /// - /// An object can delegate the job of managing and tracking advisory events to an OLE advise holder, to which you obtain a - /// pointer by calling CreateOleAdviseHolder. The returned IOleAdviseHolder interface has three methods for sending advisory - /// notifications, as well as IOleAdviseHolder::Advise, IOleAdviseHolder::Unadvise, and IOleAdviseHolder::EnumAdvise methods - /// that are identical to those for IOleObject. Calls to IOleObject::Advise, IOleObject::Unadvise, or - /// IOleObject::EnumAdvise are delegated to corresponding methods in the advise holder. - /// - /// To destroy the advise holder, simply call IUnknown::Release on the IOleAdviseHolder interface. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleobject-advise HRESULT Advise( IAdviseSink *pAdvSink, - // DWORD *pdwConnection ); - [PreserveSig] - HRESULT Advise(IAdviseSink pAdvSink, out uint pdwConnection); - - /// Deletes a previously established advisory connection. - /// - /// Contains a token of nonzero value, which was previously returned from IOleObject::Advise through its pdwConnection parameter. - /// - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// E_FAIL - /// The operation failed. - /// - /// - /// OLE_E_NOCONNECTION - /// dwConnection does not represent a valid advisory connection. - /// - /// - /// - /// - /// Normally, containers call IOleObject::Unadvise at shutdown or when an object is deleted. In certain cases, containers - /// can call this method on objects that are running but not currently visible as a way of reducing the overhead of maintaining - /// multiple advisory connections. The easiest way to implement this method is to delegate the call to IOleObject::Unadvise. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleobject-unadvise HRESULT Unadvise( DWORD dwConnection ); - [PreserveSig] - HRESULT Unadvise(uint dwConnection); - - /// - /// Retrieves a pointer to an enumerator that can be used to enumerate the advisory connections registered for an object, so a - /// container can know what to release prior to closing down. - /// - /// - /// Address of IEnumSTATDATA pointer variable that receives the interface pointer to the enumerator object. If the object does - /// not have any advisory connections or if an error occurs, the implementation must set ppenumAdvise to NULL. Each time an - /// object receives a successful call to IOleObject::EnumAdvise, it must increase the reference count on ppenumAdvise. It is the - /// caller's responsibility to call Release when it is done with the ppenumAdvise. - /// - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// E_NOTIMPL - /// EnumAdvise is not supported. - /// - /// - /// - /// - /// - /// The IOleObject::EnumAdvise method supplies an enumerator that provides a way for containers to keep track of advisory - /// connections registered for their objects. A container normally would call this function so that it can instruct an object to - /// release each of its advisory connections prior to closing down. - /// - /// - /// The enumerator to which you get access through IOleObject::EnumAdvise enumerates items of type STATDATA. Upon - /// receiving the pointer, the container can then loop through STATDATA and call IOleObject::Unadvise for each enumerated connection. - /// - /// - /// The usual way to implement this function is to delegate the call to the IOleAdviseHolder interface. Only the pAdvise - /// and dwConnection members of STATDATA are relevant for IOleObject::EnumAdvise. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleobject-enumadvise HRESULT EnumAdvise( IEnumSTATDATA - // **ppenumAdvise ); - [PreserveSig] - HRESULT EnumAdvise(out IEnumSTATDATA ppenumAdvise); - - /// Retrieves the status of an object at creation and loading. - /// - /// The aspect of an object about which status information is being requested. The value is obtained from the enumeration DVASPECT. - /// - /// Pointer to where the status information is returned. This parameter cannot be NULL. - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// OLE_S_USEREG - /// Delegate the retrieval of miscellaneous status information to the default handler's implementation of this method. - /// - /// - /// CO_E_CLASSNOTREG - /// There is no CLSID registered for the object. - /// - /// - /// CO_E_READREGDB - /// Error accessing the registry. - /// - /// - /// - /// - /// - /// A container normally calls IOleObject::GetMiscStatus when it creates or loads an object in order to determine how to - /// display the object and what types of behaviors it supports. - /// - /// - /// Objects store status information in the registry. If the object is not running, the default handler's implementation of - /// IOleObject::GetMiscStatus retrieves this information from the registry. If the object is running, the default handler - /// invokes IOleObject::GetMiscStatus on the object itself. - /// - /// - /// The information that is actually stored in the registry varies with individual objects. The status values to be returned are - /// defined in the enumeration OLEMISC. - /// - /// - /// The default value of IOleObject::GetMiscStatus is used if a subkey corresponding to the specified DVASPECT is not - /// found. To set an OLE control, specify DVASPECT==1. This will cause the following to occur in the registry: - /// - /// HKEY_CLASSES_ROOT\CLSID\ . . .MiscStatus = 1 - /// Notes to Implementers - /// Implementation normally consists of delegating the call to the default handler. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleobject-getmiscstatus HRESULT GetMiscStatus( DWORD - // dwAspect, DWORD *pdwStatus ); - [PreserveSig] - HRESULT GetMiscStatus(DVASPECT dwAspect, out uint pdwStatus); - - /// Specifies the color palette that the object application should use when it edits the specified object. - /// Pointer to a LOGPALETTE structure that specifies the recommended palette. - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// E_NOTIMPL - /// Object does not support setting palettes. - /// - /// - /// OLE_E_PALETTE - /// Invalid LOGPALETTE structure pointed to by pLogPal. - /// - /// - /// OLE_E_NOTRUNNING - /// Object must be running to perform this operation. - /// - /// - /// - /// - /// The IOleObject::SetColorScheme method sends the container application's recommended color palette to the object - /// application, which is not obliged to use it. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleobject-setcolorscheme HRESULT SetColorScheme( - // LOGPALETTE *pLogpal ); - [PreserveSig] - HRESULT SetColorScheme(IntPtr pLogpal); - } - - /// - /// The IOleWindow interface provides methods that allow an application to obtain the handle to the various windows that participate - /// in in-place activation, and also to enter and exit context-sensitive help mode. - /// - [PInvokeData("Oleidl.h")] - [ComImport, Guid("00000114-0000-0000-C000-000000000046"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] - public interface IOleWindow - { - /// - /// Retrieves a handle to one of the windows participating in in-place activation (frame, document, parent, or in-place object window). - /// - /// A pointer to a variable that receives the window handle. - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// E_FAIL - /// The object is windowless. - /// - /// - /// E_OUTOFMEMORY - /// There is insufficient memory available for this operation. - /// - /// - /// E_UNEXPECTED - /// An unexpected error has occurred. - /// - /// - /// - /// - /// - /// Five types of windows comprise the windows hierarchy. When a object is active in place, it has access to some or all of - /// these windows. - /// - /// - /// - /// Window - /// Description - /// - /// - /// Frame - /// The outermost main window where the container application's main menu resides. - /// - /// - /// Document - /// The window that displays the compound document containing the embedded object to the user. - /// - /// - /// Pane - /// - /// The subwindow of the document window that contains the object's view. Applicable only for applications with split-pane windows. - /// - /// - /// - /// Parent - /// - /// The container window that contains that object's view. The object application installs its window as a child of this window. - /// - /// - /// - /// In-place - /// - /// The window containing the active in-place object. The object application creates this window and installs it as a child of - /// its hatch window, which is a child of the container's parent window. - /// - /// - /// - /// - /// Each type of window has a different role in the in-place activation architecture. However, it is not necessary to employ a - /// separate physical window for each type. Many container applications use the same window for their frame, document, pane, and - /// parent windows. - /// - /// - [PreserveSig] - HRESULT GetWindow(out HWND phwnd); - - /// Determines whether context-sensitive help mode should be entered during an in-place activation session. - /// - /// if help mode should be entered; if it should be exited. - /// - /// - /// - /// This method returns S_OK if the help mode was entered or exited successfully, depending on the value passed in . Other possible return values include the following.
- /// - /// - /// - /// Return code - /// Description - /// - /// - /// E_INVALIDARG - /// The specified value is not valid. - /// - /// - /// E_OUTOFMEMORY - /// There is insufficient memory available for this operation. - /// - /// - /// E_UNEXPECTED - /// An unexpected error has occurred. - /// - /// - /// - /// - /// Applications can invoke context-sensitive help when the user: - /// - /// presses SHIFT+F1, then clicks a topic - /// presses F1 when a menu item is selected - /// - /// - /// When SHIFT+F1 is pressed, either the frame or active object can receive the keystrokes. If the container's frame receives - /// the keystrokes, it calls its containing document's IOleWindow::ContextSensitiveHelp method with set to . This propagates the help state to all of its in-place objects so they can - /// correctly handle the mouse click or WM_COMMAND. - /// - /// - /// If an active object receives the SHIFT+F1 keystrokes, it calls the container's IOleWindow::ContextSensitiveHelp method with - /// set to , which then recursively calls each of its in-place sites until - /// there are no more to be notified. The container then calls its document's or frame's IOleWindow::ContextSensitiveHelp method - /// with set to . - /// - /// When in context-sensitive help mode, an object that receives the mouse click can either: - /// - /// Ignore the click if it does not support context-sensitive help. - /// - /// Tell all the other objects to exit context-sensitive help mode with ContextSensitiveHelp set to FALSE and then provide help - /// for that context. - /// - /// - /// - /// An object in context-sensitive help mode that receives a WM_COMMAND should tell all the other in-place objects to exit - /// context-sensitive help mode and then provide help for the command. - /// - /// - /// If a container application is to support context-sensitive help on menu items, it must either provide its own message filter - /// so that it can intercept the F1 key or ask the OLE library to add a message filter by calling OleSetMenuDescriptor, passing - /// valid, non-NULL values for the lpFrame and lpActiveObj parameters. - /// - /// - [PreserveSig] - HRESULT ContextSensitiveHelp([MarshalAs(UnmanagedType.Bool)] bool fEnterMode); - } - - /// - /// Parses a displayable name string to convert it into a moniker for custom moniker implementations. - /// Display name parsing is necessary when the end user inputs a string to identify a component, as in the following situations: - /// + /// A pointer to the IAdviseSink interface on the advisory sink that should be informed of changes. + /// + /// A pointer to a token that can be passed to the IOleAdviseHolder::Unadvise method to delete the advisory connection. The + /// calling object is responsible for calling both IUnknown::AddRef and IUnknown::Release on this pointer. + /// + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// /// + /// E_INVALIDARG + /// The supplied IAdviseSink interface pointer is invalid. + /// + /// + /// + /// + /// + /// Containers, object handlers, and link objects all create advise sinks to receive notification of changes in + /// compound-document objects of interest, such as embedded or linked objects. OLE objects of interest to these objects must + /// implement the IOleObject interface, which includes several advisory methods, including IOleObject::Advise. A call to this + /// method must set up an advisory connection with any advise sink that calls it, and maintain each connection until it is + /// closed. It must be able to handle more than one advisory connection at a time. + /// + /// + /// IOleAdviseHolder::Advise is intended to be used to simplify the implementation of IOleObject::Advise. You can get a + /// pointer to the OLE implementation of IOleAdviseHolder by calling CreateOleAdviseHolder, and then, to implement + /// IOleObject::Advise, just delegate the call to IOleAdviseHolder::Advise. Other IOleAdviseHolder methods are + /// intended to implement other IOleObject advisory methods. + /// + /// + /// If the attempt to establish an advisory connection is successful, the object receiving the call returns a nonzero value + /// through pdwConnection. If the attempt fails, the object returns a zero. To delete an advisory connection, the object with + /// the advise sink passes this nonzero token back to the object by calling IOleAdviseHolder::Advise. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleadviseholder-advise HRESULT Advise( IAdviseSink + // *pAdvise, DWORD *pdwConnection ); + [PreserveSig] + HRESULT Advise([In] IAdviseSink pAdvise, out uint pdwConnection); + + /// Deletes a previously established advisory connection. + /// The value previously returned by IOleAdviseHolder::Advise in pdwConnection. + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// OLE_E_NOCONNECTION + /// The dwConnection parameter does not represent a valid advisory connection. + /// + /// + /// + /// + /// + /// IOleAdviseHolder::Unadvise is intended to be used to implement IOleObject::Unadvise to delete an advisory connection. + /// In general, you would use the OLE advise holder having obtained a pointer through a call to CreateOleAdviseHolder. + /// + /// + /// Typically, containers call this method at shutdown or when an object is deleted. In certain cases, containers could call + /// this method on objects that are running but not currently visible, as a way of reducing the overhead of maintaining multiple + /// advisory connections. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleadviseholder-unadvise HRESULT Unadvise( DWORD + // dwConnection ); + [PreserveSig] + HRESULT Unadvise(uint dwConnection); + + /// Creates an enumerator that can be used to enumerate the advisory connections currently established for an object. + /// + /// A pointer to an IEnumSTATDATA pointer variable that receives the interface pointer to the new enumerator. If this parameter + /// is NULL, there are presently no advisory connections on the object, or an error occurred. The advise holder is responsible + /// for incrementing the reference count on the IEnumSTATDATA pointer this method supplies. It is the caller's responsibility to + /// call IUnknown::Release when it is finished with the pointer. + /// + /// This method returns S_OK on success. + /// + /// + /// IOleAdviseHolder::EnumAdvise creates an enumerator that can be used to enumerate an object's established advisory + /// connections. The method supplies a pointer to the IEnumSTATDATA interface on this enumerator. Advisory connection + /// information for each connection is stored in the STATDATA structure, and the enumerator must be able to enumerate these structures. + /// + /// + /// For this method, the only relevant structure members are pAdvise and dwConnection. Other members contain data + /// advisory information. When you call the enumeration methods, and while an enumeration is in progress, the effect of + /// registering or revoking advisory connections on what is to be enumerated is undefined. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleadviseholder-enumadvise HRESULT EnumAdvise( + // IEnumSTATDATA **ppenumAdvise ); + [PreserveSig] + HRESULT EnumAdvised(out IEnumSTATDATA ppenumAdvise); + + /// + /// Sends notification to all advisory sinks currently registered with the advise holder that the name of object has changed. + /// + /// A pointer to the new full moniker of the object. + /// This method returns S_OK if advise sinks were sent IAdviseSink::OnRename notifications. + /// + /// SendOnRename calls IAdviseSink::OnRename to advise the calling object, which must have already established an + /// advisory connection, that the object has a new moniker. If you are using the OLE advise holder (having obtained a pointer + /// through a call to CreateOleAdviseHolder), you can call SendOnRename in the implementation of IOleObject::SetMoniker, + /// when you have determined that the operation is successful. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleadviseholder-sendonrename HRESULT SendOnRename( + // IMoniker *pmk ); + [PreserveSig] + HRESULT SendOnRename(IMoniker pmk); + + /// + /// Sends notification to all advisory sinks currently registered with the advise holder that the object has been saved. + /// + /// This method returns S_OK if advise sinks were sent IAdviseSink::OnSave notifications. + /// + /// + /// SendOnSave calls IAdviseSink::OnSave to advise the calling object (client), which must have already established an + /// advisory connection, that the object has been saved. If you are using the OLE advise holder (having obtained a pointer + /// through a call to CreateOleAdviseHolder), you can call SendOnSave whenever you save the object the advise holder is + /// associated with. + /// + /// + /// To take the object from the running state to the loaded state, the client calls IOleObject::Close. Within that + /// implementation, if the user wants to save the object to persistent storage, the object calls IOleClientSite::SaveObject, + /// followed by the call to SendOnSave. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleadviseholder-sendonsave HRESULT SendOnSave( ); + [PreserveSig] + HRESULT SendOnSave(); + + /// Sends notification to all advisory sinks currently registered with the advise holder that the object has closed. + /// + /// This method returns S_OK if advise sinks were notified of the close operation through a call to the IAdviseSink::OnClose method. + /// + /// + /// SendOnClose must call IAdviseSink::OnClose on all advise sinks that have a valid advisory connection with the object, + /// whenever the object goes from the running state to the loaded state. This occurs through a call to IOleObject::Close, so you + /// can call SendOnClose when you determine that a Close operation has been successful. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleadviseholder-sendonclose HRESULT SendOnClose( ); + [PreserveSig] + HRESULT SendOnClose(); + } + + /// + /// Provides control of the presentation data that gets cached inside of an object. Cached presentation data is available to the + /// container of the object even when the server application is not running or is unavailable. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nn-oleidl-iolecache + [PInvokeData("oleidl.h", MSDNShortId = "b5ef85d0-b54e-4831-87f1-ac6763179181")] + [ComImport, InterfaceType(ComInterfaceType.InterfaceIsIUnknown), Guid("0000011e-0000-0000-C000-000000000046")] + public interface IOleCache + { + /// Specifies the format and other data to be cached inside an embedded object. + /// + /// A pointer to a FORMATETC structure that specifies the format and other data to be cached. View caching is specified by + /// passing a zero clipboard format in pformatetc. + /// + /// + /// A group of flags that control the caching. Possible values come from the ADVF enumeration. When used in this context, for a + /// cache, these values have specific meanings, which are outlined in Remarks. Refer to the ADVF enumeration for a more + /// detailed description. + /// + /// + /// A variable that receives the identifier of this connection, which can later be used to turn caching off (by passing it to + /// IOleCache::Uncache). If this value is 0, the connection was not established. The OLE-provided implementation uses nonzero + /// numbers for connection identifiers. + /// + /// + /// + /// IOleCache::Cache can specify either data caching or view (presentation) caching. To specify data caching, a valid + /// data format must be passed in pformatetc. For view caching, the cache object itself decides on the format to cache, so a + /// caller would pass a zero data format in pformatetc as follows: + /// + /// + /// A custom object handler can choose not to store data in a given format. Instead, it can synthesize it on demand when requested. + /// + /// + /// The advf value specifies a member of the ADVF enumeration. When one of these values (or an OR'd combination of more than one + /// value) is used in this context, these values mean the following. + /// + /// + /// + /// ADVF Value + /// Description + /// + /// + /// ADVF_NODATA /// - /// A compound document application that supports linked components typically supports the Edit:Links... dialog box. Through - /// this dialog box, the end user can enter a display name to specify a new link source for a specified linked component. The - /// compound document needs to have this input string converted into a moniker. + /// The cache is not to be updated by changes made to the running object. Instead, the container will update the cache by + /// explicitly calling IOleCache::SetData, IDataObject::SetData, or IOleCache2::UpdateCache. This flag is usually used when the + /// iconic aspect of an object is being cached. /// /// /// + /// ADVF_ONLYONCE /// - /// A script language such as the macro language of a spreadsheet can allow textual references to a component. The language's - /// interpreter needs to have such a reference converted into a moniker in order to execute the macro. + /// Update the cache one time only. After the update is complete, the advisory connection between the object and the cache is + /// disconnected. The source object for the advisory connection calls the Release method. + /// + /// + /// + /// ADVF_PRIMEFIRST + /// + /// The object is not to wait for the data or view to change before updating the cache. OR'd with ADVF_ONLYONCE, this parameter + /// provides an asynchronous IDataObject::GetData call. + /// + /// + /// + /// ADVFCACHE_NOHANDLER + /// Synonym for ADVFCACHE_FORCEBUILTIN. + /// + /// + /// ADVFCACHE_FORCEBUILTIN + /// + /// Used by DLL object applications and object handlers that draw their objects to cache presentation data to ensure that there + /// is a presentation in the cache. This ensures that the data can be retrieved even when the object or handler code is not available. + /// + /// + /// + /// ADVFCACHE_ONSAVE + /// + /// Updates the cached representation only when the object containing the cache is saved. The cache is also updated when the OLE + /// object changes from the running state back to the loaded state (because a subsequent save operation would require running + /// the object again). /// /// /// - /// This interface is not supported for use across machine boundaries. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nn-oleidl-iparsedisplayname - [PInvokeData("oleidl.h", MSDNShortId = "37844d9b-35ce-4d30-8a58-dac4c671896f")] - [ComImport, Guid("0000011a-0000-0000-C000-000000000046"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] - public interface IParseDisplayName - { - /// Parses the specified display name and creates a corresponding moniker. - /// A pointer to the bind context to be used in this binding operation. See IBindCtx. - /// The display name to be parsed. - /// - /// A pointer to a variable that receives the number of characters in the display name that correspond to the ppmkOut moniker. - /// - /// - /// A pointer to an IMoniker pointer variable that receives the interface pointer to the resulting moniker. If an error occurs, - /// the implementation sets *ppmkOut to NULL. If *ppmkOut is non- NULL, the implementation must call AddRef; it is - /// the caller's responsibility to call Release. - /// - /// - /// This method can return the standard return values E_OUTOFMEMORY and E_UNEXPECTED, as well as the following values. - /// - /// - /// Return code - /// Description - /// - /// - /// S_OK - /// The method completed successfully. - /// - /// - /// MK_E_SYNTAX - /// - /// There is a syntax error in the display name. Parsing failed because pszDisplayName could only be partially resolved into a - /// moniker. In this case, *pchEaten has the number of characters that were successfully parsed into a moniker prefix. The - /// parameter ppmkOut should be NULL. - /// - /// - /// - /// MK_E_NOOBJECT - /// The display name does not identify a component in this namespace. - /// - /// - /// E_INVALIDARG - /// One or more parameters are not valid. - /// - /// - /// - /// - /// - /// In general, the maximum prefix of pszDisplayName that is syntactically valid and that represents an object should be - /// consumed by this method and converted to a moniker. - /// - /// - /// Typically, this method is called by MkParseDisplayName or MkParseDisplayNameEx. In the initial step of the parsing - /// operation, these functions can retrieve the IParseDisplayName interface directly from an instance of a class identified with - /// either the "@ProgID" or "ProgID" notation. Subsequent parsing steps can query for the interface on an intermediate object. - /// - /// - /// The main loops of MkParseDisplayName and MkParseDisplayNameEx find the next moniker piece by calling the equivalent method - /// in the IMoniker interface, that is, IMoniker::ParseDisplayName, on the moniker that it currently holds. In this call to - /// IMoniker::ParseDisplayName, the MkParseDisplayName or MkParseDisplayNameEx function passes NULL - /// in the pmkToLeft parameter. If the moniker currently held is a generic composite, the call to - /// IMoniker::ParseDisplayName is forwarded by that composite onto its last piece, passing the prefix of the composite to - /// the left of the piece in pmkToLeft. - /// - /// - /// Some moniker classes will be able to handle this parsing internally to themselves because they are designed to designate - /// only certain kinds of objects. Others will need to bind to the object that they designate to accomplish the parsing process. - /// As is usual, these objects should not be released by IMoniker::ParseDisplayName but instead should be transferred to the - /// bind context via IBindCtx::RegisterObjectBound or IBindCtx::GetRunningObjectTable followed by IRunningObjectTable::Register - /// for release at a later time. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iparsedisplayname-parsedisplayname HRESULT - // ParseDisplayName( IBindCtx *pbc, LPOLESTR pszDisplayName, ULONG *pchEaten, IMoniker **ppmkOut ); - [PreserveSig] - HRESULT ParseDisplayName(IBindCtx pbc, [MarshalAs(UnmanagedType.LPWStr)] string pszDisplayName, out uint pchEaten, out IMoniker ppmkOut); - } - - /// - /// - /// Enables an object to display itself directly without passing a data object to the caller. In addition, this interface can create - /// and manage a connection with an advise sink so the caller can be notified of changes in the view object. - /// - /// - /// The caller can request specific representations and specific target devices. For example, a caller can ask for either an - /// object's content or an iconic representation. Also, the caller can ask the object to compose a picture for a target device that - /// is independent of the drawing device context. As a result, the picture can be composed for one target device and drawn on - /// another device context. For example, to provide a print preview operation, you can compose the drawing for a printer target - /// device but actually draw the representation on the display. - /// - /// - /// The IViewObject interface is similar to IDataObject; except that IViewObject places a representation of the data - /// onto a device context while IDataObject places the representation onto a transfer medium. - /// - /// - /// Unlike most other interfaces, IViewObject cannot be marshaled to another process. This is because device contexts are - /// only effective in the context of one process. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nn-oleidl-iviewobject - [PInvokeData("oleidl.h", MSDNShortId = "NN:oleidl.IViewObject")] - [ComImport, Guid("0000010d-0000-0000-C000-000000000046"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] - public interface IViewObject - { - /// Draws a representation of an object onto the specified device context. - /// - /// Specifies the aspect to be drawn, that is, how the object is to be represented. Representations include content, an icon, a - /// thumbnail, or a printed document. Valid values are taken from the enumerations DVASPECT and DVASPECT2. Note that newer - /// objects and containers that support optimized drawing interfaces support the DVASPECT2 enumeration values. Older - /// objects and containers that do not support optimized drawing interfaces may not support DVASPECT2. Windowless objects - /// allow only DVASPECT _CONTENT, DVASPECT _OPAQUE, and DVASPECT _TRANSPARENT. - /// - /// - /// Portion of the object that is of interest for the draw operation. Its interpretation varies depending on the value in the - /// dwAspect parameter. See the DVASPECT enumeration for more information. - /// - /// - /// Pointer to additional information in a DVASPECTINFO structure that enables drawing optimizations depending on the aspect - /// specified. Note that newer objects and containers that support optimized drawing interfaces support this parameter as well. - /// Older objects and containers that do not support optimized drawing interfaces always specify NULL for this parameter. - /// - /// - /// Pointer to the DVTARGETDEVICE structure that describes the device for which the object is to be rendered. If NULL, - /// the view should be rendered for the default target device (typically the display). A value other than NULL is - /// interpreted in conjunction with hdcTargetDev and hdcDraw. For example, if hdcDraw specifies a printer as the device context, - /// the ptd parameter points to a structure describing that printer device. The data may actually be printed if hdcTargetDev is - /// a valid value or it may be displayed in print preview mode if hdcTargetDev is NULL. - /// - /// - /// Information context for the target device indicated by the ptd parameter from which the object can extract device metrics - /// and test the device's capabilities. If ptd is NULL; the object should ignore the value in the hdcTargetDev parameter. - /// - /// - /// Device context on which to draw. For a windowless object, the hdcDraw parameter should be in MM_TEXT mapping mode with its - /// logical coordinates matching the client coordinates of the containing window. For a windowless object, the device context - /// should be in the same state as the one normally passed by a WM_PAINT message. - /// - /// - /// Pointer to a RECTL structure specifying the rectangle on hdcDraw and in which the object should be drawn. This parameter - /// controls the positioning and stretching of the object. This parameter should be NULL to draw a windowless in-place - /// active object. In every other situation, NULL is not a legal value and should result in an E_INVALIDARG error code. - /// If the container passes a non- NULL value to a windowless object, the object should render the requested aspect into - /// the specified device context and rectangle. A container can request this from a windowless object to render a second, - /// non-active view of the object or to print the object. - /// - /// - /// - /// If hdcDraw is a metafile device context, pointer to a RECTL structure specifying the bounding rectangle in the underlying - /// metafile. The rectangle structure contains the window extent and window origin. These values are useful for drawing - /// metafiles. The rectangle indicated by lprcBounds is nested inside this lprcWBounds rectangle; they are in the same - /// coordinate space. - /// - /// If hdcDraw is not a metafile device context; lprcWBounds will be NULL. - /// - /// - /// - /// Pointer to a callback function that the view object should call periodically during a lengthy drawing operation to determine - /// whether the operation should continue or be canceled. This function returns TRUE to continue drawing. It returns - /// FALSE to stop the drawing in which case IViewObject::Draw returns DRAW_E_ABORT. - /// - /// dwContinue - /// - /// - /// Value to pass as a parameter to the function pointed to by the pfnContinue parameter. Typically, dwContinue is a pointer to - /// an application-defined structure needed inside the callback function. - /// - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// OLE_E_BLANK - /// No data to draw from. - /// - /// - /// DRAW_E_ABORT - /// Draw operation aborted. - /// - /// - /// VIEW_E_DRAW - /// Error in drawing. - /// - /// - /// DV_E_LINDEX - /// Invalid value for lindex; currently only -1 is supported. - /// - /// - /// DV_E_DVASPECT - /// Invalid value for dwAspect. - /// - /// - /// OLE_E_INVALIDRECT - /// Invalid rectangle. - /// - /// - /// - /// - /// - /// A container application issues a call to IViewObject::Draw to create a representation of a contained object. This - /// method draws the specified piece (lindex) of the specified view (dwAspect and pvAspect) on the specified device context - /// (hdcDraw). Formatting, fonts, and other rendering decisions are made on the basis of the target device specified by the ptd parameter. - /// - /// - /// There is a relationship between the dwDrawAspect value and the lprcbounds value. The lprcbounds value specifies the - /// rectangle on hdcDraw into which the drawing is to be mapped. For DVASPECT_THUMBNAIL, DVASPECT _ICON, and - /// DVASPECT _SMALLICON, the object draws whatever it wants to draw, and it maps it into the space given in the best way. - /// Some objects might scale to fit while some might scale to fit but preserve the aspect ratio. In addition, some might scale - /// so the drawing appears at full width, but the bottom is cropped. The container can suggest a size via IOleObject::SetExtent, - /// but it has no control over the rendering size. In the case of DVASPECT _CONTENT, the IViewObject::Draw - /// implementation should either use the extents given by IOleObject::SetExtent or use the bounding rectangle given in - /// the lprcBounds parameter. - /// - /// - /// For newer objects that support optimized drawing techniques and for windowless objects, this method should be used as follows: - /// - /// - /// - /// New drawing aspects are supported in dwAspect as defined in DVASPECT2. - /// - /// - /// - /// The pvAspect parameter can be used to pass additional information allowing drawing optimizations through the DVASPECTINFO structure. - /// - /// - /// - /// - /// The IViewObject::Draw method can be called to redraw a windowless in-place active object by setting the lrpcBounds - /// parameter to NULL. In every other situation, NULL is an illegal value and should result in an E_INVALIDARG - /// error code. A windowless object uses the rectangle passed by the activation verb or calls IOleInPlaceObject::SetObjectRects - /// instead of using this parameter. If the container passes a non- NULL value to a windowless object, the object should - /// render the requested aspect into the specified device context and rectangle. A container can request this from a windowless - /// object to render a second, non-active view of the object or to print the object. See the IOleInPlaceSiteWindowless interface - /// for more information on drawing windowless objects. - /// - /// - /// - /// - /// For windowless objects, the dwAspect parameter only allows the DVASPECT_CONTENT, DVASPECT _OPAQUE, and - /// DVASPECT _TRANSPARENT aspects. - /// - /// - /// - /// - /// For a windowless object, the hdcDraw parameter should be in MM_TEXT mapping mode with its logical coordinates matching the - /// client coordinates of the containing window. For a windowless object, the device context should be in the same state as the - /// one normally passed by a WM_PAINT message. - /// - /// - /// - /// - /// To maintain compatibility with older objects and containers that do not support drawing optimizations, all objects, - /// rectangular or not, are required to maintain an origin and a rectangular extent. This allows the container to still consider - /// all its embedded objects as rectangles and to pass them appropriate rendering rectangles in Draw. - /// - /// - /// An object's extent depends on the drawing aspect. For non-rectangular objects, the extent should be the size of a rectangle - /// covering the entire aspect. By convention, the origin of an object is the top-left corner of the rectangle of the - /// DVASPECT_CONTENT aspect. In other words, the origin always coincides with the top-left corner of the rectangle maintained by - /// the object's site, even for a non-rectangular object. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iviewobject-draw HRESULT Draw( DWORD dwDrawAspect, LONG - // lindex, void *pvAspect, DVTARGETDEVICE *ptd, HDC hdcTargetDev, HDC hdcDraw, LPCRECTL lprcBounds, LPCRECTL lprcWBounds, BOOL(* - // )(ULONG_PTR dwContinue) pfnContinue, ULONG_PTR dwContinue ); - unsafe HRESULT Draw(DVASPECT dwDrawAspect, int lindex, [In, Optional] DVASPECTINFO* pvAspect, [In, Optional] DVTARGETDEVICE* ptd, - [In, Optional] HDC hdcTargetDev, [In] HDC hdcDraw, [In, Optional] PRECT lprcBounds, [In, Optional] PRECT lprcWBounds, - [In, Optional, MarshalAs(UnmanagedType.FunctionPtr)] Func pfnContinue, [In, Optional] IntPtr dwContinue); - - /// - /// Returns the logical palette that the object will use for drawing in its IViewObject::Draw method with the corresponding parameters. - /// - /// - /// Specifies how the object is to be represented. Representations include content, an icon, a thumbnail, or a printed document. - /// Valid values are taken from the enumeration DVASPECT. See the DVASPECT enumeration for more information. - /// - /// - /// Portion of the object that is of interest for the draw operation. Its interpretation varies with dwDrawAspect. See the - /// DVASPECT enumeration for more information. - /// - /// - /// Pointer to additional information about the view of the object specified in dwDrawAspect. Since none of the current aspects - /// support additional information, pvAspect must always be NULL. - /// - /// - /// Pointer to the DVTARGETDEVICE structure that describes the device for which the object is to be rendered. If NULL, - /// the view should be rendered for the default target device (typically the display). A value other than NULL is - /// interpreted in conjunction with hicTargetDev and hdcDraw. For example, if hdcDraw specifies a printer as the device context, - /// ptd points to a structure describing that printer device. The data may actually be printed if hicTargetDev is a valid value - /// or it may be displayed in print preview mode if hicTargetDev is NULL. - /// - /// - /// Information context for the target device indicated by the ptd parameter from which the object can extract device metrics - /// and test the device's capabilities. If ptd is NULL, the object should ignore the hicTargetDev parameter. - /// - /// - /// Address of LOGPALETTE pointer variable that receives a pointer to the LOGPALETTE structure. The LOGPALETTE structure - /// contains the set of colors that would be used if IViewObject::Draw were called with the same parameters for dwAspect, - /// lindex, pvAspect, ptd, and hicTargetDev. If ppColorSet is NULL, the object does not use a palette. - /// - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// S_FALSE - /// Set of colors is empty or the object will not give out the information. - /// - /// - /// OLE_E_BLANK - /// No presentation data for object. - /// - /// - /// DV_E_LINDEX - /// Invalid value for lindex; currently only -1 is supported. - /// - /// - /// DV_E_DVASPECT - /// Invalid value for dwAspect. - /// - /// - /// E_INVALIDARG - /// One or more of the supplied parameter values is invalid. - /// - /// - /// E_OUTOFMEMORY - /// Insufficient memory available for this operation. - /// - /// - /// - /// - /// - /// The IViewObject::GetColorSet method recursively queries any nested objects and returns a color set that represents - /// the union of all colors requested. The color set eventually percolates to the top-level container that owns the window - /// frame. This container can call IViewObject::GetColorSet on each of its embedded objects to obtain all the colors - /// needed to draw the embedded objects. The container can use the color sets obtained in conjunction with other colors it needs - /// for itself to set the overall color palette. - /// - /// - /// The OLE-provided implementation of IViewObject::GetColorSet looks at the data it has on hand to draw the picture. If - /// CF_DIB is the drawing format, the palette found in the bitmap is used. For a regular bitmap, no color information is - /// returned. If the drawing format is a metafile, the object handler enumerates the metafile looking for a CreatePalette - /// metafile record. If one is found, the handler uses it as the color set. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iviewobject-getcolorset HRESULT GetColorSet( DWORD - // dwDrawAspect, LONG lindex, void *pvAspect, DVTARGETDEVICE *ptd, HDC hicTargetDev, LOGPALETTE **ppColorSet ); - unsafe HRESULT GetColorSet(DVASPECT dwDrawAspect, int lindex, [In, Optional] DVASPECTINFO* pvAspect, [In, Optional] DVTARGETDEVICE* ptd, - [In, Optional] HDC hicTargetDev, out LOGPALETTE ppColorSet); - - /// - /// Freezes the drawn representation of an object so that it will not change until the IViewObject::Unfreeze method is called. - /// The most common use of this method is for banded printing. - /// - /// - /// Specifies how the object is to be represented. Representations include content, an icon, a thumbnail, or a printed document. - /// Valid values are taken from the enumeration DVASPECT. See the DVASPECT enumeration for more information. - /// - /// - /// Portion of the object that is of interest for the draw operation. Its interpretation varies with dwAspect. See the DVASPECT - /// enumeration for more information. - /// - /// - /// Pointer to additional information about the view of the object specified in dwAspect. Since none of the current aspects - /// support additional information, pvAspect must always be NULL. - /// - /// - /// Pointer to where an identifying DWORD key is returned. This unique key is later used to cancel the freeze by calling - /// IViewObject::Unfreeze. This key is an index that the default cache uses to keep track of which object is frozen. - /// - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// VIEW_S_ALREADY_FROZEN - /// Presentation has already been frozen. The value of pdwFreeze is the identifying key of the already frozen object. - /// - /// - /// OLE_E_BLANK - /// Presentation not in cache. - /// - /// - /// DV_E_LINDEX - /// Invalid value for lindex; currently; only -1 is supported. - /// - /// - /// DV_E_DVASPECT - /// Invalid value for dwAspect. - /// - /// - /// - /// - /// - /// The IViewObject::Freeze method causes the view object to freeze its drawn representation until a subsequent call to - /// IViewObject::Unfreeze releases it. After calling IViewObject::Freeze, successive calls to IViewObject::Draw with the - /// same parameters produce the same picture until IViewObject::Unfreeze is called. - /// - /// - /// IViewObject::Freeze is not part of the persistent state of the object and does not continue across unloads and - /// reloads of the object. - /// - /// The most common use of this method is for banded printing. - /// - /// While in a frozen state, view notifications are not sent. Pending view notifications are deferred to the subsequent call to IViewObject::Unfreeze. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iviewobject-freeze HRESULT Freeze( DWORD dwDrawAspect, - // LONG lindex, void *pvAspect, DWORD *pdwFreeze ); - unsafe HRESULT Freeze(DVASPECT dwDrawAspect, int lindex, [In, Optional] DVASPECTINFO* pvAspect, out uint pdwFreeze); - - /// - /// Releases a drawing that was previously frozen using IViewObject::Freeze. The most common use of this method is for banded printing. - /// - /// - /// Contains a key previously returned from IViewObject::Freeze that determines which view object to unfreeze. - /// - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// OLE_E_NOCONNECTION - /// Error in the unfreezing process or the object is currently not frozen. - /// - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iviewobject-unfreeze HRESULT Unfreeze( DWORD dwFreeze ); - HRESULT Unfreeze(uint dwFreeze); - - /// - /// Establishes a connection between the view object and an advise sink so that the advise sink can be notified about changes in - /// the object's view. - /// - /// - /// View for which the advisory connection is being set up. Valid values are taken from the enumeration DVASPECT. See the - /// DVASPECT enumeration for more information. - /// - /// - /// - /// Contains a group of flags for controlling the advisory connection. Valid values are from the enumeration ADVF. However, only - /// some of the possible ADVF values are relevant for this method. The following table briefly describes the relevant - /// values. See the ADVF enumeration for a more detailed description. - /// - /// - /// - /// Value - /// Meaning - /// - /// - /// ADVF_ONLYONCE - /// Causes the advisory connection to be destroyed after the first notification is sent. - /// - /// - /// ADVF_PRIMEFIRST - /// Causes an initial notification to be sent regardless of whether data has changed from its current state. - /// - /// - /// Note The ADVF_ONLYONCE and ADVF_PRIMEFIRST can be combined to provide an asynchronous call to IDataObject::GetData. - /// - /// - /// Pointer to the IAdviseSink interface on the advisory sink that is to be informed of changes. A NULL value deletes any - /// existing advisory connection. - /// - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// OLE_E_ADVISENOTSUPPORTED - /// Advisory notifications are not supported. - /// - /// - /// DV_E_DVASPECT - /// Invalid value for dwAspect. - /// - /// - /// E_INVALIDARG - /// One or more of the supplied values is invalid. - /// - /// - /// E_OUTOFMEMORY - /// Insufficient memory available for this operation. - /// - /// - /// - /// - /// - /// A container application that is requesting a draw operation on a view object can also register with the - /// IViewObject::SetAdvise method to be notified when the presentation of the view object changes. To find out about when - /// an object's underlying data changes, you must call IDataObject::DAdvise separately. - /// - /// To remove an existing advisory connection, call the IViewObject::SetAdvise method with pAdvSink set to NULL. - /// If the view object changes, a call is made to the appropriate advise sink through its IAdviseSink::OnViewChange method. - /// - /// At any time, a given view object can support only one advisory connection. Therefore, when IViewObject::SetAdvise is - /// called and the view object is already holding on to an advise sink pointer, OLE releases the existing pointer before the new - /// one is registered. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iviewobject-setadvise HRESULT SetAdvise( DWORD aspects, - // DWORD advf, IAdviseSink *pAdvSink ); - HRESULT SetAdvise(DVASPECT aspects, ADVF advf, [In, Optional] IAdviseSink pAdvSink); - - /// Retrieves the advisory connection on the object that was used in the most recent call to IViewObject::SetAdvise. - /// - /// Pointer to where the dwAspect parameter from the previous IViewObject::SetAdvise call is returned. If this pointer is - /// NULL, the caller does not permit this value to be returned. - /// - /// - /// Pointer to where the advf parameter from the previous IViewObject::SetAdvise call is returned. If this pointer is - /// NULL, the caller does not permit this value to be returned. - /// - /// - /// Address of IAdviseSink pointer variable that receives the interface pointer to the advise sink. The connection to this - /// advise sink must have been established with a previous IViewObject::SetAdvise call, which provides the pAdvSink parameter. - /// If ppvAdvSink is NULL, there is no established advisory connection. - /// - /// This method returns S_OK on success. - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iviewobject-getadvise HRESULT GetAdvise( DWORD *pAspects, - // DWORD *pAdvf, IAdviseSink **ppAdvSink ); - unsafe HRESULT GetAdvise([Out, Optional] DVASPECT* pAspects, [Out, Optional] ADVF* pAdvf, [Out, Optional] IntPtr ppAdvSink); - } - - /// - /// - /// An extension to the IViewObject interface which returns the size of the drawing for a given view of an object. You can prevent - /// the object from being run if it isn't already running by calling this method instead of IOleObject::GetExtent. - /// - /// - /// Like the IViewObject interface, IViewObject2 cannot be marshaled to another process. This is because device contexts are - /// only effective in the context of one process. - /// - /// The OLE-provided default implementation provides the size of the object in the cache. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nn-oleidl-iviewobject2 - [PInvokeData("oleidl.h", MSDNShortId = "NN:oleidl.IViewObject2")] - [ComImport, Guid("00000127-0000-0000-C000-000000000046"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] - public interface IViewObject2 : IViewObject - { - /// Draws a representation of an object onto the specified device context. - /// - /// Specifies the aspect to be drawn, that is, how the object is to be represented. Representations include content, an icon, a - /// thumbnail, or a printed document. Valid values are taken from the enumerations DVASPECT and DVASPECT2. Note that newer - /// objects and containers that support optimized drawing interfaces support the DVASPECT2 enumeration values. Older - /// objects and containers that do not support optimized drawing interfaces may not support DVASPECT2. Windowless objects - /// allow only DVASPECT _CONTENT, DVASPECT _OPAQUE, and DVASPECT _TRANSPARENT. - /// - /// - /// Portion of the object that is of interest for the draw operation. Its interpretation varies depending on the value in the - /// dwAspect parameter. See the DVASPECT enumeration for more information. - /// - /// - /// Pointer to additional information in a DVASPECTINFO structure that enables drawing optimizations depending on the aspect - /// specified. Note that newer objects and containers that support optimized drawing interfaces support this parameter as well. - /// Older objects and containers that do not support optimized drawing interfaces always specify NULL for this parameter. - /// - /// - /// Pointer to the DVTARGETDEVICE structure that describes the device for which the object is to be rendered. If NULL, - /// the view should be rendered for the default target device (typically the display). A value other than NULL is - /// interpreted in conjunction with hdcTargetDev and hdcDraw. For example, if hdcDraw specifies a printer as the device context, - /// the ptd parameter points to a structure describing that printer device. The data may actually be printed if hdcTargetDev is - /// a valid value or it may be displayed in print preview mode if hdcTargetDev is NULL. - /// - /// - /// Information context for the target device indicated by the ptd parameter from which the object can extract device metrics - /// and test the device's capabilities. If ptd is NULL; the object should ignore the value in the hdcTargetDev parameter. - /// - /// - /// Device context on which to draw. For a windowless object, the hdcDraw parameter should be in MM_TEXT mapping mode with its - /// logical coordinates matching the client coordinates of the containing window. For a windowless object, the device context - /// should be in the same state as the one normally passed by a WM_PAINT message. - /// - /// - /// Pointer to a RECTL structure specifying the rectangle on hdcDraw and in which the object should be drawn. This parameter - /// controls the positioning and stretching of the object. This parameter should be NULL to draw a windowless in-place - /// active object. In every other situation, NULL is not a legal value and should result in an E_INVALIDARG error code. - /// If the container passes a non- NULL value to a windowless object, the object should render the requested aspect into - /// the specified device context and rectangle. A container can request this from a windowless object to render a second, - /// non-active view of the object or to print the object. - /// - /// - /// - /// If hdcDraw is a metafile device context, pointer to a RECTL structure specifying the bounding rectangle in the underlying - /// metafile. The rectangle structure contains the window extent and window origin. These values are useful for drawing - /// metafiles. The rectangle indicated by lprcBounds is nested inside this lprcWBounds rectangle; they are in the same - /// coordinate space. - /// - /// If hdcDraw is not a metafile device context; lprcWBounds will be NULL. - /// - /// - /// - /// Pointer to a callback function that the view object should call periodically during a lengthy drawing operation to determine - /// whether the operation should continue or be canceled. This function returns TRUE to continue drawing. It returns - /// FALSE to stop the drawing in which case IViewObject::Draw returns DRAW_E_ABORT. - /// - /// dwContinue - /// - /// - /// Value to pass as a parameter to the function pointed to by the pfnContinue parameter. Typically, dwContinue is a pointer to - /// an application-defined structure needed inside the callback function. - /// - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// OLE_E_BLANK - /// No data to draw from. - /// - /// - /// DRAW_E_ABORT - /// Draw operation aborted. - /// - /// - /// VIEW_E_DRAW - /// Error in drawing. - /// - /// - /// DV_E_LINDEX - /// Invalid value for lindex; currently only -1 is supported. - /// - /// - /// DV_E_DVASPECT - /// Invalid value for dwAspect. - /// - /// - /// OLE_E_INVALIDRECT - /// Invalid rectangle. - /// - /// - /// - /// - /// - /// A container application issues a call to IViewObject::Draw to create a representation of a contained object. This - /// method draws the specified piece (lindex) of the specified view (dwAspect and pvAspect) on the specified device context - /// (hdcDraw). Formatting, fonts, and other rendering decisions are made on the basis of the target device specified by the ptd parameter. - /// - /// - /// There is a relationship between the dwDrawAspect value and the lprcbounds value. The lprcbounds value specifies the - /// rectangle on hdcDraw into which the drawing is to be mapped. For DVASPECT_THUMBNAIL, DVASPECT _ICON, and - /// DVASPECT _SMALLICON, the object draws whatever it wants to draw, and it maps it into the space given in the best way. - /// Some objects might scale to fit while some might scale to fit but preserve the aspect ratio. In addition, some might scale - /// so the drawing appears at full width, but the bottom is cropped. The container can suggest a size via IOleObject::SetExtent, - /// but it has no control over the rendering size. In the case of DVASPECT _CONTENT, the IViewObject::Draw - /// implementation should either use the extents given by IOleObject::SetExtent or use the bounding rectangle given in - /// the lprcBounds parameter. - /// - /// - /// For newer objects that support optimized drawing techniques and for windowless objects, this method should be used as follows: - /// - /// - /// - /// New drawing aspects are supported in dwAspect as defined in DVASPECT2. - /// - /// - /// - /// The pvAspect parameter can be used to pass additional information allowing drawing optimizations through the DVASPECTINFO structure. - /// - /// - /// - /// - /// The IViewObject::Draw method can be called to redraw a windowless in-place active object by setting the lrpcBounds - /// parameter to NULL. In every other situation, NULL is an illegal value and should result in an E_INVALIDARG - /// error code. A windowless object uses the rectangle passed by the activation verb or calls IOleInPlaceObject::SetObjectRects - /// instead of using this parameter. If the container passes a non- NULL value to a windowless object, the object should - /// render the requested aspect into the specified device context and rectangle. A container can request this from a windowless - /// object to render a second, non-active view of the object or to print the object. See the IOleInPlaceSiteWindowless interface - /// for more information on drawing windowless objects. - /// - /// - /// - /// - /// For windowless objects, the dwAspect parameter only allows the DVASPECT_CONTENT, DVASPECT _OPAQUE, and - /// DVASPECT _TRANSPARENT aspects. - /// - /// - /// - /// - /// For a windowless object, the hdcDraw parameter should be in MM_TEXT mapping mode with its logical coordinates matching the - /// client coordinates of the containing window. For a windowless object, the device context should be in the same state as the - /// one normally passed by a WM_PAINT message. - /// - /// - /// - /// - /// To maintain compatibility with older objects and containers that do not support drawing optimizations, all objects, - /// rectangular or not, are required to maintain an origin and a rectangular extent. This allows the container to still consider - /// all its embedded objects as rectangles and to pass them appropriate rendering rectangles in Draw. - /// - /// - /// An object's extent depends on the drawing aspect. For non-rectangular objects, the extent should be the size of a rectangle - /// covering the entire aspect. By convention, the origin of an object is the top-left corner of the rectangle of the - /// DVASPECT_CONTENT aspect. In other words, the origin always coincides with the top-left corner of the rectangle maintained by - /// the object's site, even for a non-rectangular object. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iviewobject-draw HRESULT Draw( DWORD dwDrawAspect, LONG - // lindex, void *pvAspect, DVTARGETDEVICE *ptd, HDC hdcTargetDev, HDC hdcDraw, LPCRECTL lprcBounds, LPCRECTL lprcWBounds, BOOL(* - // )(ULONG_PTR dwContinue) pfnContinue, ULONG_PTR dwContinue ); - new unsafe HRESULT Draw(DVASPECT dwDrawAspect, int lindex, [In, Optional] DVASPECTINFO* pvAspect, [In, Optional] DVTARGETDEVICE* ptd, - [In, Optional] HDC hdcTargetDev, [In] HDC hdcDraw, [In, Optional] PRECT lprcBounds, [In, Optional] PRECT lprcWBounds, - [In, Optional, MarshalAs(UnmanagedType.FunctionPtr)] Func pfnContinue, [In, Optional] IntPtr dwContinue); - - /// - /// Returns the logical palette that the object will use for drawing in its IViewObject::Draw method with the corresponding parameters. - /// - /// - /// Specifies how the object is to be represented. Representations include content, an icon, a thumbnail, or a printed document. - /// Valid values are taken from the enumeration DVASPECT. See the DVASPECT enumeration for more information. - /// - /// - /// Portion of the object that is of interest for the draw operation. Its interpretation varies with dwDrawAspect. See the - /// DVASPECT enumeration for more information. - /// - /// - /// Pointer to additional information about the view of the object specified in dwDrawAspect. Since none of the current aspects - /// support additional information, pvAspect must always be NULL. - /// - /// - /// Pointer to the DVTARGETDEVICE structure that describes the device for which the object is to be rendered. If NULL, - /// the view should be rendered for the default target device (typically the display). A value other than NULL is - /// interpreted in conjunction with hicTargetDev and hdcDraw. For example, if hdcDraw specifies a printer as the device context, - /// ptd points to a structure describing that printer device. The data may actually be printed if hicTargetDev is a valid value - /// or it may be displayed in print preview mode if hicTargetDev is NULL. - /// - /// - /// Information context for the target device indicated by the ptd parameter from which the object can extract device metrics - /// and test the device's capabilities. If ptd is NULL, the object should ignore the hicTargetDev parameter. - /// - /// - /// Address of LOGPALETTE pointer variable that receives a pointer to the LOGPALETTE structure. The LOGPALETTE structure - /// contains the set of colors that would be used if IViewObject::Draw were called with the same parameters for dwAspect, - /// lindex, pvAspect, ptd, and hicTargetDev. If ppColorSet is NULL, the object does not use a palette. - /// - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// S_FALSE - /// Set of colors is empty or the object will not give out the information. - /// - /// - /// OLE_E_BLANK - /// No presentation data for object. - /// - /// - /// DV_E_LINDEX - /// Invalid value for lindex; currently only -1 is supported. - /// - /// - /// DV_E_DVASPECT - /// Invalid value for dwAspect. - /// - /// - /// E_INVALIDARG - /// One or more of the supplied parameter values is invalid. - /// - /// - /// E_OUTOFMEMORY - /// Insufficient memory available for this operation. - /// - /// - /// - /// - /// - /// The IViewObject::GetColorSet method recursively queries any nested objects and returns a color set that represents - /// the union of all colors requested. The color set eventually percolates to the top-level container that owns the window - /// frame. This container can call IViewObject::GetColorSet on each of its embedded objects to obtain all the colors - /// needed to draw the embedded objects. The container can use the color sets obtained in conjunction with other colors it needs - /// for itself to set the overall color palette. - /// - /// - /// The OLE-provided implementation of IViewObject::GetColorSet looks at the data it has on hand to draw the picture. If - /// CF_DIB is the drawing format, the palette found in the bitmap is used. For a regular bitmap, no color information is - /// returned. If the drawing format is a metafile, the object handler enumerates the metafile looking for a CreatePalette - /// metafile record. If one is found, the handler uses it as the color set. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iviewobject-getcolorset HRESULT GetColorSet( DWORD - // dwDrawAspect, LONG lindex, void *pvAspect, DVTARGETDEVICE *ptd, HDC hicTargetDev, LOGPALETTE **ppColorSet ); - new unsafe HRESULT GetColorSet(DVASPECT dwDrawAspect, int lindex, [In, Optional] DVASPECTINFO* pvAspect, [In, Optional] DVTARGETDEVICE* ptd, - [In, Optional] HDC hicTargetDev, out LOGPALETTE ppColorSet); - - /// - /// Freezes the drawn representation of an object so that it will not change until the IViewObject::Unfreeze method is called. - /// The most common use of this method is for banded printing. - /// - /// - /// Specifies how the object is to be represented. Representations include content, an icon, a thumbnail, or a printed document. - /// Valid values are taken from the enumeration DVASPECT. See the DVASPECT enumeration for more information. - /// - /// - /// Portion of the object that is of interest for the draw operation. Its interpretation varies with dwAspect. See the DVASPECT - /// enumeration for more information. - /// - /// - /// Pointer to additional information about the view of the object specified in dwAspect. Since none of the current aspects - /// support additional information, pvAspect must always be NULL. - /// - /// - /// Pointer to where an identifying DWORD key is returned. This unique key is later used to cancel the freeze by calling - /// IViewObject::Unfreeze. This key is an index that the default cache uses to keep track of which object is frozen. - /// - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// VIEW_S_ALREADY_FROZEN - /// Presentation has already been frozen. The value of pdwFreeze is the identifying key of the already frozen object. - /// - /// - /// OLE_E_BLANK - /// Presentation not in cache. - /// - /// - /// DV_E_LINDEX - /// Invalid value for lindex; currently; only -1 is supported. - /// - /// - /// DV_E_DVASPECT - /// Invalid value for dwAspect. - /// - /// - /// - /// - /// - /// The IViewObject::Freeze method causes the view object to freeze its drawn representation until a subsequent call to - /// IViewObject::Unfreeze releases it. After calling IViewObject::Freeze, successive calls to IViewObject::Draw with the - /// same parameters produce the same picture until IViewObject::Unfreeze is called. - /// - /// - /// IViewObject::Freeze is not part of the persistent state of the object and does not continue across unloads and - /// reloads of the object. - /// - /// The most common use of this method is for banded printing. - /// - /// While in a frozen state, view notifications are not sent. Pending view notifications are deferred to the subsequent call to IViewObject::Unfreeze. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iviewobject-freeze HRESULT Freeze( DWORD dwDrawAspect, - // LONG lindex, void *pvAspect, DWORD *pdwFreeze ); - new unsafe HRESULT Freeze(DVASPECT dwDrawAspect, int lindex, [In, Optional] DVASPECTINFO* pvAspect, out uint pdwFreeze); - - /// - /// Releases a drawing that was previously frozen using IViewObject::Freeze. The most common use of this method is for banded printing. - /// - /// - /// Contains a key previously returned from IViewObject::Freeze that determines which view object to unfreeze. - /// - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// OLE_E_NOCONNECTION - /// Error in the unfreezing process or the object is currently not frozen. - /// - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iviewobject-unfreeze HRESULT Unfreeze( DWORD dwFreeze ); - new HRESULT Unfreeze(uint dwFreeze); - - /// - /// Establishes a connection between the view object and an advise sink so that the advise sink can be notified about changes in - /// the object's view. - /// - /// - /// View for which the advisory connection is being set up. Valid values are taken from the enumeration DVASPECT. See the - /// DVASPECT enumeration for more information. - /// - /// - /// - /// Contains a group of flags for controlling the advisory connection. Valid values are from the enumeration ADVF. However, only - /// some of the possible ADVF values are relevant for this method. The following table briefly describes the relevant - /// values. See the ADVF enumeration for a more detailed description. - /// - /// - /// - /// Value - /// Meaning - /// - /// - /// ADVF_ONLYONCE - /// Causes the advisory connection to be destroyed after the first notification is sent. - /// - /// - /// ADVF_PRIMEFIRST - /// Causes an initial notification to be sent regardless of whether data has changed from its current state. - /// - /// - /// Note The ADVF_ONLYONCE and ADVF_PRIMEFIRST can be combined to provide an asynchronous call to IDataObject::GetData. - /// - /// - /// Pointer to the IAdviseSink interface on the advisory sink that is to be informed of changes. A NULL value deletes any - /// existing advisory connection. - /// - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// OLE_E_ADVISENOTSUPPORTED - /// Advisory notifications are not supported. - /// - /// - /// DV_E_DVASPECT - /// Invalid value for dwAspect. - /// - /// - /// E_INVALIDARG - /// One or more of the supplied values is invalid. - /// - /// - /// E_OUTOFMEMORY - /// Insufficient memory available for this operation. - /// - /// - /// - /// - /// - /// A container application that is requesting a draw operation on a view object can also register with the - /// IViewObject::SetAdvise method to be notified when the presentation of the view object changes. To find out about when - /// an object's underlying data changes, you must call IDataObject::DAdvise separately. - /// - /// To remove an existing advisory connection, call the IViewObject::SetAdvise method with pAdvSink set to NULL. - /// If the view object changes, a call is made to the appropriate advise sink through its IAdviseSink::OnViewChange method. - /// - /// At any time, a given view object can support only one advisory connection. Therefore, when IViewObject::SetAdvise is - /// called and the view object is already holding on to an advise sink pointer, OLE releases the existing pointer before the new - /// one is registered. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iviewobject-setadvise HRESULT SetAdvise( DWORD aspects, - // DWORD advf, IAdviseSink *pAdvSink ); - new HRESULT SetAdvise(DVASPECT aspects, ADVF advf, [In, Optional] IAdviseSink pAdvSink); - - /// Retrieves the advisory connection on the object that was used in the most recent call to IViewObject::SetAdvise. - /// - /// Pointer to where the dwAspect parameter from the previous IViewObject::SetAdvise call is returned. If this pointer is - /// NULL, the caller does not permit this value to be returned. - /// - /// - /// Pointer to where the advf parameter from the previous IViewObject::SetAdvise call is returned. If this pointer is - /// NULL, the caller does not permit this value to be returned. - /// - /// - /// Address of IAdviseSink pointer variable that receives the interface pointer to the advise sink. The connection to this - /// advise sink must have been established with a previous IViewObject::SetAdvise call, which provides the pAdvSink parameter. - /// If ppvAdvSink is NULL, there is no established advisory connection. - /// - /// This method returns S_OK on success. - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iviewobject-getadvise HRESULT GetAdvise( DWORD *pAspects, - // DWORD *pAdvf, IAdviseSink **ppAdvSink ); - new unsafe HRESULT GetAdvise([Out, Optional] DVASPECT* pAspects, [Out, Optional] ADVF* pAdvf, [Out, Optional] IntPtr ppAdvSink); - - /// Retrieves the size that the specified view object will be drawn on the specified target device. - /// - /// Requested view of the object whose size is of interest. Possible values are taken from the DVASPECT and DVASPECT2 - /// enumerations. Note that newer objects and containers that support optimized drawing interfaces support the DVASPECT2 - /// enumeration values. Older objects and containers that do not support optimized drawing interfaces may not support DVASPECT2. - /// - /// The portion of the object that is of interest. Currently, the only possible value is -1. - /// - /// A pointer to the DVTARGETDEVICE structure defining the target device for which the object's size should be returned. - /// - /// A pointer to where the object's size is returned. - /// - /// This method returns S_OK on success. Other possible return values include the following. - /// - /// - /// Return code - /// Description - /// - /// - /// OLE_E_BLANK - /// An appropriate cache is not available. - /// - /// - /// - /// - /// The OLE-provided implementation of IViewObject2::GetExtent searches the cache for the size of the view object. - /// The IOleObject::GetExtent method in the IOleObject interface provides some of the same information as IViewObject2::GetExtent. - /// - /// This method must return the same size as DVASPECT_CONTENT for all the new aspects in DVASPECT2. IOleObject::GetExtent must - /// do the same thing. - /// - /// - /// If one of the new aspects is requested in dwAspect, this method can either fail or return the same rectangle as for the - /// DVASPECT_CONTENT aspect. - /// - /// Notes to Callers - /// - /// To prevent the object from being run if it isn't already running, you can call IViewObject2::GetExtent rather than - /// IOleObject::GetExtent to determine the size of the presentation to be drawn. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iviewobject2-getextent HRESULT GetExtent( DWORD - // dwDrawAspect, LONG lindex, DVTARGETDEVICE *ptd, LPSIZEL lpsizel ); - HRESULT GetExtent(uint dwDrawAspect, int lindex, in DVTARGETDEVICE ptd, out SIZE lpsizel); - } - - /// - /// Contains information about the accelerators supported by a container during an in-place session. The structure is used in the - /// IOleInPlaceSite::GetWindowContext method and the OleTranslateAccelerator function. - /// - /// - /// When an object is being in-place activated, its server calls the container's IOleInPlaceSite::GetWindowContext method, which - /// fills in an OLEINPLACEFRAMEINFO structure. During an in-place session, the message loop of an EXE server passes a pointer - /// to the OLEINPLACEFRAMEINFO structure to OleTranslateAccelerator. OLE uses the information in this structure to determine - /// whether a message maps to one of the container's accelerators. /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/ns-oleidl-oleinplaceframeinfo typedef struct tagOIFI { UINT cb; BOOL - // fMDIApp; HWND hwndFrame; HACCEL haccel; UINT cAccelEntries; } OLEINPLACEFRAMEINFO, *LPOLEINPLACEFRAMEINFO; - [PInvokeData("oleidl.h", MSDNShortId = "e09445d2-61e5-4691-b51e-746e0cc91c00")] - [StructLayout(LayoutKind.Sequential)] - public struct OLEINPLACEFRAMEINFO - { - /// - /// The size of this structure, in bytes. The object server must specify sizeof( OLEINPLACEFRAMEINFO) in the structure it - /// passes to IOleInPlaceSite::GetWindowContext. The container can then use this size to determine the structure's version. - /// - public uint cb; + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolecache-cache HRESULT Cache( FORMATETC *pformatetc, + // DWORD advf, DWORD *pdwConnection ); + uint Cache(in FORMATETC pformatetc, ADVF advf); - /// Indicates whether the container is an MDI application. - [MarshalAs(UnmanagedType.Bool)] - public bool fMDIApp; + /// Removes a cache connection created previously using IOleCache::Cache. + /// + /// The cache connection to be removed. This nonzero value was returned by IOleCache::Cache when the cache was originally established. + /// + /// + /// The IOleCache::Uncache method removes a cache connection that was created in a prior call to IOleCache::Cache. It + /// uses the dwConnection parameter that was returned by the prior call to IOleCache::Cache. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolecache-uncache HRESULT Uncache( DWORD dwConnection ); + void Uncache(uint dwConnection); - /// A handle to the container's top-level frame window. - public HWND hwndFrame; + /// Creates an enumerator that can be used to enumerate the current cache connections. + /// + /// A pointer to an IEnumSTATDATA pointer variable that receives the interface pointer to the new enumerator object. If this + /// parameter is NULL, there are no cache connections at this time. + /// + /// + /// The enumerator object returned by this method implements the IEnumSTATDATA interface. IEnumSTATDATA enumerates the + /// data stored in an array of STATDATA structures containing information about current cache connections. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolecache-enumcache + IEnumSTATDATA EnumCache(); - /// A handle to the accelerator table that the container wants to use during an in-place editing session. - public HACCEL haccel; + /// Fills the cache as needed using the data provided by the specified data object. + /// A pointer to the IDataObject interface on the data object from which the cache is to be initialized. + /// + /// InitCache is usually used when creating an object from a drag-and-drop operation or from a clipboard paste operation. + /// It fills the cache as needed with presentation data from all the data formats provided by the data object provided on the + /// clipboard or in the drag-and-drop operation. Helper functions like OleCreateFromData or OleCreateLinkFromData call this + /// method when needed. If a container does not use these helper functions to create compound document objects, it can use + /// IOleCache::Cache to set up the cache entries which are then filled by InitCache. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolecache-initcache HRESULT InitCache( IDataObject + // *pDataObject ); + void InitCache(IDataObject pDataObject); - /// The number of accelerators in haccel. - public uint cAccelEntries; - } + /// Initializes the cache with data in a specified format and on a specified medium. + /// + /// A pointer to a FORMATETC structure that specifies the format of the presentation data being placed in the cache. + /// + /// + /// A pointer to a STGMEDIUM structure that specifies the storage medium that contains the presentation data. + /// + /// + /// Indicates the ownership of the storage medium after completion of the method. If fRelease is TRUE, the cache takes + /// ownership, freeing the medium when it is finished using it. When fRelease is FALSE, the caller retains ownership and + /// is responsible for freeing the medium. The cache can only use the storage medium for the duration of the call. + /// + /// + /// + /// IOleCache::SetData is usually called when an object is created from the clipboard or through a drag-and-drop + /// operation, and Embed Source data is used to create the object. + /// + /// + /// IOleCache::SetData and IOleCache::InitCache are very similar. There are two main differences. The first difference is + /// that while IOleCache::InitCache initializes the cache with the presentation format provided by the data object, + /// IOleCache::SetData initializes it with a single format. Second, the IOleCache::SetData method ignores the + /// ADVF_NODATA flag while IOleCache::InitCache obeys this flag. + /// + /// A container can use this method to maintain a single aspect of an object, such as the icon aspect of the object. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolecache-setdata HRESULT SetData( FORMATETC *pformatetc, + // STGMEDIUM *pmedium, BOOL fRelease ); + void SetData(in FORMATETC pformatetc, in STGMEDIUM pmedium, [MarshalAs(UnmanagedType.Bool)] bool fRelease); + } + + /// Enables object clients to selectively update each cache that was created with IOleCache::Cache. + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nn-oleidl-iolecache2 + [PInvokeData("oleidl.h", MSDNShortId = "NN:oleidl.IOleCache2")] + [ComImport, Guid("00000128-0000-0000-C000-000000000046"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IOleCache2 : IOleCache + { + /// Specifies the format and other data to be cached inside an embedded object. + /// + /// A pointer to a FORMATETC structure that specifies the format and other data to be cached. View caching is specified by + /// passing a zero clipboard format in pformatetc. + /// + /// + /// A group of flags that control the caching. Possible values come from the ADVF enumeration. When used in this context, for a + /// cache, these values have specific meanings, which are outlined in Remarks. Refer to the ADVF enumeration for a more + /// detailed description. + /// + /// + /// A variable that receives the identifier of this connection, which can later be used to turn caching off (by passing it to + /// IOleCache::Uncache). If this value is 0, the connection was not established. The OLE-provided implementation uses nonzero + /// numbers for connection identifiers. + /// + /// + /// + /// IOleCache::Cache can specify either data caching or view (presentation) caching. To specify data caching, a valid + /// data format must be passed in pformatetc. For view caching, the cache object itself decides on the format to cache, so a + /// caller would pass a zero data format in pformatetc as follows: + /// + /// + /// A custom object handler can choose not to store data in a given format. Instead, it can synthesize it on demand when requested. + /// + /// + /// The advf value specifies a member of the ADVF enumeration. When one of these values (or an OR'd combination of more than one + /// value) is used in this context, these values mean the following. + /// + /// + /// + /// ADVF Value + /// Description + /// + /// + /// ADVF_NODATA + /// + /// The cache is not to be updated by changes made to the running object. Instead, the container will update the cache by + /// explicitly calling IOleCache::SetData, IDataObject::SetData, or IOleCache2::UpdateCache. This flag is usually used when the + /// iconic aspect of an object is being cached. + /// + /// + /// + /// ADVF_ONLYONCE + /// + /// Update the cache one time only. After the update is complete, the advisory connection between the object and the cache is + /// disconnected. The source object for the advisory connection calls the Release method. + /// + /// + /// + /// ADVF_PRIMEFIRST + /// + /// The object is not to wait for the data or view to change before updating the cache. OR'd with ADVF_ONLYONCE, this parameter + /// provides an asynchronous IDataObject::GetData call. + /// + /// + /// + /// ADVFCACHE_NOHANDLER + /// Synonym for ADVFCACHE_FORCEBUILTIN. + /// + /// + /// ADVFCACHE_FORCEBUILTIN + /// + /// Used by DLL object applications and object handlers that draw their objects to cache presentation data to ensure that there + /// is a presentation in the cache. This ensures that the data can be retrieved even when the object or handler code is not available. + /// + /// + /// + /// ADVFCACHE_ONSAVE + /// + /// Updates the cached representation only when the object containing the cache is saved. The cache is also updated when the OLE + /// object changes from the running state back to the loaded state (because a subsequent save operation would require running + /// the object again). + /// + /// + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolecache-cache HRESULT Cache( FORMATETC *pformatetc, + // DWORD advf, DWORD *pdwConnection ); + new uint Cache(in FORMATETC pformatetc, ADVF advf); + + /// Removes a cache connection created previously using IOleCache::Cache. + /// + /// The cache connection to be removed. This nonzero value was returned by IOleCache::Cache when the cache was originally established. + /// + /// + /// The IOleCache::Uncache method removes a cache connection that was created in a prior call to IOleCache::Cache. It + /// uses the dwConnection parameter that was returned by the prior call to IOleCache::Cache. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolecache-uncache HRESULT Uncache( DWORD dwConnection ); + new void Uncache(uint dwConnection); + + /// Creates an enumerator that can be used to enumerate the current cache connections. + /// + /// A pointer to an IEnumSTATDATA pointer variable that receives the interface pointer to the new enumerator object. If this + /// parameter is NULL, there are no cache connections at this time. + /// + /// + /// The enumerator object returned by this method implements the IEnumSTATDATA interface. IEnumSTATDATA enumerates the + /// data stored in an array of STATDATA structures containing information about current cache connections. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolecache-enumcache + new IEnumSTATDATA EnumCache(); + + /// Fills the cache as needed using the data provided by the specified data object. + /// A pointer to the IDataObject interface on the data object from which the cache is to be initialized. + /// + /// InitCache is usually used when creating an object from a drag-and-drop operation or from a clipboard paste operation. + /// It fills the cache as needed with presentation data from all the data formats provided by the data object provided on the + /// clipboard or in the drag-and-drop operation. Helper functions like OleCreateFromData or OleCreateLinkFromData call this + /// method when needed. If a container does not use these helper functions to create compound document objects, it can use + /// IOleCache::Cache to set up the cache entries which are then filled by InitCache. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolecache-initcache HRESULT InitCache( IDataObject + // *pDataObject ); + new void InitCache(IDataObject pDataObject); + + /// Initializes the cache with data in a specified format and on a specified medium. + /// + /// A pointer to a FORMATETC structure that specifies the format of the presentation data being placed in the cache. + /// + /// + /// A pointer to a STGMEDIUM structure that specifies the storage medium that contains the presentation data. + /// + /// + /// Indicates the ownership of the storage medium after completion of the method. If fRelease is TRUE, the cache takes + /// ownership, freeing the medium when it is finished using it. When fRelease is FALSE, the caller retains ownership and + /// is responsible for freeing the medium. The cache can only use the storage medium for the duration of the call. + /// + /// + /// + /// IOleCache::SetData is usually called when an object is created from the clipboard or through a drag-and-drop + /// operation, and Embed Source data is used to create the object. + /// + /// + /// IOleCache::SetData and IOleCache::InitCache are very similar. There are two main differences. The first difference is + /// that while IOleCache::InitCache initializes the cache with the presentation format provided by the data object, + /// IOleCache::SetData initializes it with a single format. Second, the IOleCache::SetData method ignores the + /// ADVF_NODATA flag while IOleCache::InitCache obeys this flag. + /// + /// A container can use this method to maintain a single aspect of an object, such as the icon aspect of the object. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolecache-setdata HRESULT SetData( FORMATETC *pformatetc, + // STGMEDIUM *pmedium, BOOL fRelease ); + new void SetData(in FORMATETC pformatetc, in STGMEDIUM pmedium, [MarshalAs(UnmanagedType.Bool)] bool fRelease); + + /// Updates the specified caches. This method is used when the application needs precise control over caching. + /// + /// A pointer to the IDataObject interface on the data object from which the cache is updated. Object handlers and in-process + /// servers typically pass a non- NULL value. A container application usually passes NULL, and the source is + /// obtained from the currently running object. + /// + /// + /// The type of cache to be updated. This parameter can be one or more of the following values. + /// + /// + /// Value + /// Meaning + /// + /// + /// UPDFCACHE_NODATACACHE + /// Updates caches created by using ADVF_NODATA in the call to IOleCache::Cache. + /// + /// + /// UPDFCACHE_ONSAVECACHE + /// Updates caches created by using ADVFCACHE_ONSAVE in the call to IOleCache::Cache. + /// + /// + /// UPDFCACHE_ONSTOPCACHE + /// Updates caches created by using ADVFCACHE_ONSTOP in the call to IOleCache::Cache. + /// + /// + /// UPDFCACHE_NORMALCACHE + /// Dynamically updates the caches (as is normally done when the object sends out OnDataChange notices). + /// + /// + /// UPDFCACHE_IFBLANK + /// Updates the cache if blank, regardless of any other flag specified. + /// + /// + /// UPDFCACHE_ONLYIFBLANK + /// Updates only caches that are blank. + /// + /// + /// UPDFCACHE_ IFBLANKORONSAVECACHE + /// The equivalent of using an OR operation to combine UPDFCACHE_IFBLANK and UPDFCACHE_ONSAVECACHE. + /// + /// + /// UPDFCACHE_ALL + /// Updates all caches. + /// + /// + /// UPDFCACHE_ ALLBUTNODATACACHE + /// + /// Updates all caches except those created with ADVF_NODATA in the call to IOleCache::Cache. Thus, you can control updates to + /// the caches created with the ADVF_NODATA flag and only update these caches explicitly. + /// + /// + /// + /// + /// This parameter is reserved and must be NULL. + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// E_INVALIDARG + /// One of the arguments is not valid. + /// + /// + /// E_UNEXPECTED + /// An unexpected error has occurred. + /// + /// + /// E_OUTOFMEMORY + /// Insufficient memory is available for this operation. + /// + /// + /// OLE_E_NOTRUNNING + /// The specified pDataObject is not running. + /// + /// + /// CACHE_E_NOCACHE_UPDATED + /// None of the caches were updated. + /// + /// + /// CACHE_S_SOMECACHES_NOTUPDATED + /// Some of the caches were updated. + /// + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolecache2-updatecache HRESULT UpdateCache( LPDATAOBJECT + // pDataObject, DWORD grfUpdf, LPVOID pReserved ); + HRESULT UpdateCache(IDataObject pDataObject, UPDFCACHE grfUpdf, [In, Optional] IntPtr pReserved); + + /// Discards the caches found in memory. + /// + /// + /// A value from the DISCARDCACHE enumeration that indicates whether data is to be saved prior to being discarded. Containers + /// that have drawn a large object and need to free up memory can specify DISCARDCACHE_SAVEIFDIRTY so that the newest + /// presentation is saved for the next time the object must be drawn. + /// + /// + /// Containers that have activated an embedded object, made some changes, and then called IOleObject::Close with OLECLOSE_NOSAVE + /// to roll back the changes can specify DISCARDCACHE_NOSAVE to ensure that the native and presentation data are not out of synchronization. + /// + /// + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// OLE_E_NOSTORAGE + /// There is no storage available for saving the data in the cache. + /// + /// + /// STG_E_MEDIUMFULL + /// The storage medium is full. + /// + /// + /// + /// + /// + /// The IOleCache2::DiscardCache method is commonly used to handle low memory conditions by freeing memory currently + /// being used by presentation caches. + /// + /// After it is discarded, a cache will satisfy subsequent IDataObject::GetData calls by reverting to disk-based data. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolecache2-discardcache HRESULT DiscardCache( DWORD + // dwDiscardOptions ); + HRESULT DiscardCache(DISCARDCACHE dwDiscardOptions); + } + + /// + /// Provides proper maintenance of caches. It maintains the caches by connecting the running object's IDataObject implementation to + /// the cache, allowing the cache to receive notifications from the running object. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nn-oleidl-iolecachecontrol + [PInvokeData("oleidl.h", MSDNShortId = "NN:oleidl.IOleCacheControl")] + [ComImport, Guid("00000129-0000-0000-C000-000000000046"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IOleCacheControl + { + /// + /// Notifies the cache that the data source object has entered the running state so that the cache object can establish advise + /// sinks as needed. + /// + /// A pointer to the IDataObject interface on the object that is entering the running state. + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// E_INVALIDARG + /// One of the arguments is not valid. + /// + /// + /// E_UNEXPECTED + /// An unexpected error has occurred. + /// + /// + /// E_OUTOFMEMORY + /// Insufficient memory is available for this operation. + /// + /// + /// + /// + /// + /// When OnRun is called, the cache sets up advisory connections as necessary with the source data object so it can + /// receive notifications. The advisory connection created between the running object and the cache is destroyed when + /// IOleCacheControl::OnStop is called. + /// + /// + /// Some object handlers or in-process servers might use the cache passively, and not call OnRun. These applications must + /// call IOleCache2::UpdateCache, IOleCache::InitCache, or IOleCache::SetData to fill the cache when necessary to ensure that + /// the cache gets updated. + /// + /// + /// OnRun does not add a reference count on the pointer to IDataObject passed in pDataObject. Because it is the + /// responsibility of the caller of OleRun to ensure that the lifetime of the pDataObject pointer lasts until OnStop is called, + /// the caller must be holding a pointer to IDataObject on the data object of interest. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolecachecontrol-onrun HRESULT OnRun( LPDATAOBJECT + // pDataObject ); + HRESULT OnRun(IDataObject pDataObject); /// - /// Indicates the number of menu items in each of the six menu groups of a menu shared between a container and an object server - /// during an in-place editing session. This is the mechanism for building a shared menu. + /// Notifies the cache that it should terminate any existing advise sinks. No indication is given as to whether a connection + /// actually existed. /// - [PInvokeData("Oleidl.h", MSDNShortId = "ms693766")] - [StructLayout(LayoutKind.Sequential)] - public struct OLEMENUGROUPWIDTHS - { - /// - /// An array whose elements contain the number of menu items in each of the six menu groups of a shared in-place editing menu. - /// Each menu group can have any number of menu items. The container uses elements 0, 2, and 4 to indicate the number of menu - /// items in its File, View, and Window menu groups. The object server uses elements 1, 3, and 5 to indicate the number of menu - /// items in its Edit, Object, and Help menu groups. - /// - [MarshalAs(UnmanagedType.ByValArray, SizeConst = 6)] - public uint[] width; - } + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// E_UNEXPECTED + /// An unexpected error has occurred. + /// + /// + /// E_OUTOFMEMORY + /// Insufficient memory is available for this operation. + /// + /// + /// + /// The data advisory connection between the running object and the cache is destroyed as part of calling OnStop. + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolecachecontrol-onstop HRESULT OnStop(); + HRESULT OnStop(); + } + + /// + /// + /// Provides the primary means by which an embedded object obtains information about the location and extent of its display site, + /// its moniker, its user interface, and other resources provided by its container. An object server calls IOleClientSite to + /// request services from the container. A container must provide one instance of IOleClientSite for every compound-document + /// object it contains. + /// + /// Note This interface is not supported for use across machine boundaries. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nn-oleidl-ioleclientsite + [PInvokeData("oleidl.h", MSDNShortId = "dafee149-926a-4d08-a43d-5847682db645")] + [ComImport, Guid("00000118-0000-0000-C000-000000000046"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IOleClientSite + { + /// + /// Saves the embedded object associated with the client site. This function is synchronous; by the time it returns, the save + /// will be completed. + /// + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// E_FAIL + /// The operation has failed. + /// + /// + /// + /// + /// + /// An embedded object calls SaveObject to ask its container to save it to persistent storage when an end user chooses + /// the File Update or Exit commands. The call is synchronous, meaning that by the time it returns, the save operation will be completed. + /// + /// + /// Calls to SaveObject occur in most implementations of IOleObject::Close. Normally, when a container tells an object to + /// close, the container passes a flag specifying whether the object should save itself before closing, prompt the user for + /// instructions, or close without saving itself. If an object is instructed to save itself, either by its container or an end + /// user, it calls SaveObject to ask the container application to save the object's contents before the object closes + /// itself. If a container instructs an object not to save itself, the object should not call SaveObject. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleclientsite-saveobject HRESULT SaveObject( ); + [PreserveSig] + HRESULT SaveObject(); /// - /// Defines a verb that an object supports. The IOleObject::EnumVerbs method creates an enumerator that can enumerate these - /// structures for an object, and supplies a pointer to the enumerator's IEnumOLEVERB. + /// Retrieves a moniker for the object's client site. An object can force the assignment of its own or its container's moniker + /// by specifying a value for dwAssign. /// - // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/ns-oleidl-oleverb typedef struct tagOLEVERB { LONG lVerb; LPOLESTR - // lpszVerbName; DWORD fuFlags; DWORD grfAttribs; } OLEVERB, *LPOLEVERB; - [PInvokeData("oleidl.h", MSDNShortId = "657e3cc3-67fb-4458-8dad-f2a31df1b631")] - [StructLayout(LayoutKind.Sequential)] - public struct OLEVERB - { - /// Integer identifier associated with this verb. - public int lVerb; + /// + /// Specifies whether to get a moniker only if one already exists, force assignment of a moniker, create a temporary moniker, or + /// remove a moniker that has been assigned. In practice, you will usually request that the container force assignment of the + /// moniker. Possible values are taken from the OLEGETMONIKER enumeration. + /// + /// + /// Specifies whether to return the container's moniker, the object's moniker relative to the container, or the object's full + /// moniker. In practice, you will usually request the object's full moniker. Possible values are taken from the OLEWHICHMK enumeration. + /// + /// + /// A pointer to an IMoniker pointer variable that receives the interface pointer to the moniker for the object's client site. + /// If an error occurs, the implementation must set ppmk to NULL. Each time a container receives a call to + /// IOleClientSite::GetMoniker, it must increase the reference count on the ppmk pointer it returns. It is the caller's + /// responsibility to call Release when it is finished with the pointer. + /// + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// E_NOTIMPL + /// This container cannot assign monikers to objects. This is the case with OLE 1 containers. + /// + /// + /// + /// + /// + /// Containers implement GetMoniker as a way of passing out monikers for their embedded objects to clients that need to + /// link to those objects. + /// + /// + /// When a link is made to an embedded object or to a pseudo-object within it (a range of cells in a spreadsheet, for example), + /// the object needs a moniker to construct the composite moniker indicating the source of the link. If the embedded object does + /// not already have a moniker, it can call GetMoniker to request one. + /// + /// + /// Every container that expects to contain links to embeddings should support GetMoniker to give out + /// OLEWHICHMK_CONTAINER, thus enabling link tracking when the link client and link source files move, but maintain the same + /// relative position. + /// + /// + /// An object must not persistently store its full moniker or its container's moniker, because these can change while the object + /// is not loaded. For example, either the container or the object could be renamed, in which event, storing the container's + /// moniker or the object's full moniker would make it impossible for a client to track a link to the object. + /// + /// + /// In some very specialized cases, an object may no longer need a moniker previously assigned to it and may wish to have it + /// removed as an optimization. In such cases, the object can call GetMoniker with OLEGETMONIKER_UNASSIGN to have the + /// moniker removed. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleclientsite-getmoniker HRESULT GetMoniker( DWORD + // dwAssign, DWORD dwWhichMoniker, IMoniker **ppmk ); + [PreserveSig] + HRESULT GetMoniker(OLEGETMONIKER dwAssign, OLEWHICHMK dwWhichMoniker, out IMoniker ppmk); - /// Pointer to a string that contains the verb's name. - [MarshalAs(UnmanagedType.LPWStr)] - public string lpszVerbName; + /// Retrieves a pointer to the object's container. + /// + /// Address of IOleContainer pointer variable that receives the interface pointer to the container object. If an error occurs, + /// the implementation must set ppContainer to NULL. + /// + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// OLE_E_NOT_SUPPORTED + /// The client site is in an OLE 1 container. + /// + /// + /// E_NOINTERFACE + /// The container does not implement the IOleContainer interface. + /// + /// + /// + /// + /// + /// If a container supports links to its embedded objects, implementing GetContainer enables link clients to enumerate + /// the container's objects and recursively traverse a containment hierarchy. This method is optional but recommended for all + /// containers that expect to support links to their embedded objects. + /// + /// + /// Link clients can traverse a hierarchy of compound-document objects by recursively calling GetContainer to get a + /// pointer to the link source's container; followed by QueryInterface to get a pointer to the container's IOleObject interface + /// and, finally, IOleObject::GetClientSite to get the container's client site in its container. + /// + /// + /// Simple containers that do not support links to their embedded objects probably do not need to implement this method. + /// Instead, they can return E_NOINTERFACE and set ppContainer to NULL. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleclientsite-getcontainer HRESULT GetContainer( + // IOleContainer **ppContainer ); + [PreserveSig] + HRESULT GetContainer(out IOleContainer ppContainer); - /// - /// In Windows, a group of flags taken from the flag constants beginning with MF_ defined in AppendMenu. Containers should use - /// these flags in building an object's verb menu. All Flags defined in AppendMenu are supported except for MF_BITMAP, - /// MF_OWNERDRAW, and MF_POPUP. - /// - public uint fuFlags; + /// + /// Asks a container to display its object to the user. This method ensures that the container itself is visible and not minimized. + /// + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// OLE_E_NOT_SUPPORTED + /// Client site is in an OLE 1 container. + /// + /// + /// + /// + /// + /// After a link client binds to a link source, it commonly calls IOleObject::DoVerb on the link source, usually requesting the + /// source to perform some action requiring that it display itself to the user. As part of its implementation of + /// IOleObject::DoVerb, the link source can call ShowObject, which forces the client to show the link source as + /// best it can. If the link source's container is itself an embedded object, it will recursively invoke ShowObject on + /// its own container. + /// + /// + /// Having called the ShowObject method, a link source has no guarantee of being appropriately displayed because its + /// container may not be able to do so at the time of the call. The ShowObject method does not guarantee visibility, only + /// that the container will do the best it can. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleclientsite-showobject HRESULT ShowObject( ); + [PreserveSig] + HRESULT ShowObject(); - /// Combination of the verb attributes in the OLEVERBATTRIB enumeration. - public OLEVERBATTRIB grfAttribs; - } + /// + /// Notifies a container when an embedded object's window is about to become visible or invisible. This method does not apply to + /// an object that is activated in place and therefore has no window separate from that of its container. + /// + /// Indicates whether an object's window is open (TRUE) or closed (FALSE). + /// This method returns S_OK on success. + /// + /// An embedded object calls OnShowWindow to keep its container informed when the object is open in a window. This window + /// may or may not be currently visible to the end user. The container uses this information to shade the object's client site + /// when the object is displayed in a window, and to remove the shading when the object is not. A shaded object, having received + /// this notification, knows that it already has an open window and therefore can respond to being double-clicked by bringing + /// this window quickly to the top, instead of launching its application in order to obtain a new one. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleclientsite-onshowwindow HRESULT OnShowWindow( BOOL + // fShow ); + [PreserveSig] + HRESULT OnShowWindow([MarshalAs(UnmanagedType.Bool)] bool fShow); + + /// Asks a container to resize the display site for embedded objects. + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// E_NOTIMPL + /// Client site does not support requests for new layout. + /// + /// + /// + /// + /// This method can either increase or decrease the space. Currently, there is no standard mechanism by which a container can + /// negotiate how much room an object would like. When such a negotiation is defined, responding to this method will be optional + /// for containers. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleclientsite-requestnewobjectlayout HRESULT + // RequestNewObjectLayout( ); + [PreserveSig] + HRESULT RequestNewObjectLayout(); + } + + /// + /// Enumerates objects in a compound document or lock a container in the running state. Container and object applications both + /// implement this interface. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nn-oleidl-iolecontainer + [PInvokeData("oleidl.h", MSDNShortId = "98549309-8ac8-4391-92ab-8a62269ff579")] + [ComImport, Guid("0000011b-0000-0000-C000-000000000046"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IOleContainer : IParseDisplayName + { + /// Parses the specified display name and creates a corresponding moniker. + /// A pointer to the bind context to be used in this binding operation. See IBindCtx. + /// The display name to be parsed. + /// + /// A pointer to a variable that receives the number of characters in the display name that correspond to the ppmkOut moniker. + /// + /// + /// A pointer to an IMoniker pointer variable that receives the interface pointer to the resulting moniker. If an error occurs, + /// the implementation sets *ppmkOut to NULL. If *ppmkOut is non- NULL, the implementation must call AddRef; it is + /// the caller's responsibility to call Release. + /// + /// + /// This method can return the standard return values E_OUTOFMEMORY and E_UNEXPECTED, as well as the following values. + /// + /// + /// Return code + /// Description + /// + /// + /// S_OK + /// The method completed successfully. + /// + /// + /// MK_E_SYNTAX + /// + /// There is a syntax error in the display name. Parsing failed because pszDisplayName could only be partially resolved into a + /// moniker. In this case, *pchEaten has the number of characters that were successfully parsed into a moniker prefix. The + /// parameter ppmkOut should be NULL. + /// + /// + /// + /// MK_E_NOOBJECT + /// The display name does not identify a component in this namespace. + /// + /// + /// E_INVALIDARG + /// One or more parameters are not valid. + /// + /// + /// + /// + /// + /// In general, the maximum prefix of pszDisplayName that is syntactically valid and that represents an object should be + /// consumed by this method and converted to a moniker. + /// + /// + /// Typically, this method is called by MkParseDisplayName or MkParseDisplayNameEx. In the initial step of the parsing + /// operation, these functions can retrieve the IParseDisplayName interface directly from an instance of a class identified with + /// either the "@ProgID" or "ProgID" notation. Subsequent parsing steps can query for the interface on an intermediate object. + /// + /// + /// The main loops of MkParseDisplayName and MkParseDisplayNameEx find the next moniker piece by calling the equivalent method + /// in the IMoniker interface, that is, IMoniker::ParseDisplayName, on the moniker that it currently holds. In this call to + /// IMoniker::ParseDisplayName, the MkParseDisplayName or MkParseDisplayNameEx function passes NULL + /// in the pmkToLeft parameter. If the moniker currently held is a generic composite, the call to + /// IMoniker::ParseDisplayName is forwarded by that composite onto its last piece, passing the prefix of the composite to + /// the left of the piece in pmkToLeft. + /// + /// + /// Some moniker classes will be able to handle this parsing internally to themselves because they are designed to designate + /// only certain kinds of objects. Others will need to bind to the object that they designate to accomplish the parsing process. + /// As is usual, these objects should not be released by IMoniker::ParseDisplayName but instead should be transferred to the + /// bind context via IBindCtx::RegisterObjectBound or IBindCtx::GetRunningObjectTable followed by IRunningObjectTable::Register + /// for release at a later time. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iparsedisplayname-parsedisplayname HRESULT + // ParseDisplayName( IBindCtx *pbc, LPOLESTR pszDisplayName, ULONG *pchEaten, IMoniker **ppmkOut ); + [PreserveSig] + new HRESULT ParseDisplayName(IBindCtx pbc, [MarshalAs(UnmanagedType.LPWStr)] string pszDisplayName, out uint pchEaten, out IMoniker ppmkOut); + + /// Enumerates the objects in the current container. + /// Specifies which objects in a container are to be enumerated, as defined in the enumeration OLECONTF. + /// + /// A pointer to an IEnumUnknown pointer variable that receives the interface pointer to the enumerator object. Each time a + /// container receives a successful call to EnumObjects, it must increase the reference count on the ppenum pointer the method + /// returns. It is the caller's responsibility to call IUnknown::Release when it is done with the pointer. If an error is + /// returned, the implementation must set ppenum to NULL. + /// + /// This method returns S_OK on success. + /// + /// A container should implement EnumObjects to enable programmatic clients to find out what objects it holds. This + /// method, however, is not called in standard linking scenarios. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolecontainer-enumobjects HRESULT EnumObjects( DWORD + // grfFlags, IEnumUnknown **ppenum ); + [PreserveSig] + HRESULT EnumObjects(OLECONTF grfFlags, out IEnumUnknown ppenum); + + /// Keeps the container for embedded objects running until explicitly released. + /// Indicates whether to lock ( TRUE) or unlock ( FALSE) a container. + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// E_FAIL + /// The operation failed. + /// + /// + /// E_OUTOFMEMORY + /// Insufficient memory available for the operation. + /// + /// + /// + /// + /// An embedded object calls LockContainer to keep its container running when the object has link clients that require an + /// update. If an end user selects File Close from the container's menu, however, the container ignores all outstanding + /// LockContainer locks and closes the document anyway. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolecontainer-lockcontainer HRESULT LockContainer( BOOL + // fLock ); + [PreserveSig] + HRESULT LockContainer([MarshalAs(UnmanagedType.Bool)] bool fLock); + } + + /// + /// Provides a direct channel of communication between an in-place object and the associated application's outer-most frame window + /// and the document window within the application that contains the embedded object. The communication involves the translation of + /// messages, the state of the frame window (activated or deactivated), and the state of the document window (activated or + /// deactivated). Also, it informs the object when it needs to resize its borders, and manages modeless dialog boxes. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nn-oleidl-ioleinplaceactiveobject + [PInvokeData("oleidl.h", MSDNShortId = "b077c256-1109-494c-95c2-2d33bccbe47b")] + [ComImport, Guid("00000117-0000-0000-C000-000000000046"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IOleInPlaceActiveObject : IOleWindow + { + /// + /// Retrieves a handle to one of the windows participating in in-place activation (frame, document, parent, or in-place object window). + /// + /// A pointer to a variable that receives the window handle. + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// E_FAIL + /// The object is windowless. + /// + /// + /// E_OUTOFMEMORY + /// There is insufficient memory available for this operation. + /// + /// + /// E_UNEXPECTED + /// An unexpected error has occurred. + /// + /// + /// + /// + /// + /// Five types of windows comprise the windows hierarchy. When a object is active in place, it has access to some or all of + /// these windows. + /// + /// + /// + /// Window + /// Description + /// + /// + /// Frame + /// The outermost main window where the container application's main menu resides. + /// + /// + /// Document + /// The window that displays the compound document containing the embedded object to the user. + /// + /// + /// Pane + /// + /// The subwindow of the document window that contains the object's view. Applicable only for applications with split-pane windows. + /// + /// + /// + /// Parent + /// + /// The container window that contains that object's view. The object application installs its window as a child of this window. + /// + /// + /// + /// In-place + /// + /// The window containing the active in-place object. The object application creates this window and installs it as a child of + /// its hatch window, which is a child of the container's parent window. + /// + /// + /// + /// + /// Each type of window has a different role in the in-place activation architecture. However, it is not necessary to employ a + /// separate physical window for each type. Many container applications use the same window for their frame, document, pane, and + /// parent windows. + /// + /// + [PreserveSig] + new HRESULT GetWindow(out HWND phwnd); + + /// Determines whether context-sensitive help mode should be entered during an in-place activation session. + /// + /// if help mode should be entered; if it should be exited. + /// + /// + /// + /// This method returns S_OK if the help mode was entered or exited successfully, depending on the value passed in . Other possible return values include the following.
+ /// + /// + /// + /// Return code + /// Description + /// + /// + /// E_INVALIDARG + /// The specified value is not valid. + /// + /// + /// E_OUTOFMEMORY + /// There is insufficient memory available for this operation. + /// + /// + /// E_UNEXPECTED + /// An unexpected error has occurred. + /// + /// + /// + /// + /// Applications can invoke context-sensitive help when the user: + /// + /// presses SHIFT+F1, then clicks a topic + /// presses F1 when a menu item is selected + /// + /// + /// When SHIFT+F1 is pressed, either the frame or active object can receive the keystrokes. If the container's frame receives + /// the keystrokes, it calls its containing document's IOleWindow::ContextSensitiveHelp method with set to . This propagates the help state to all of its in-place objects so they can + /// correctly handle the mouse click or WM_COMMAND. + /// + /// + /// If an active object receives the SHIFT+F1 keystrokes, it calls the container's IOleWindow::ContextSensitiveHelp method with + /// set to , which then recursively calls each of its in-place sites until + /// there are no more to be notified. The container then calls its document's or frame's IOleWindow::ContextSensitiveHelp method + /// with set to . + /// + /// When in context-sensitive help mode, an object that receives the mouse click can either: + /// + /// Ignore the click if it does not support context-sensitive help. + /// + /// Tell all the other objects to exit context-sensitive help mode with ContextSensitiveHelp set to FALSE and then provide help + /// for that context. + /// + /// + /// + /// An object in context-sensitive help mode that receives a WM_COMMAND should tell all the other in-place objects to exit + /// context-sensitive help mode and then provide help for the command. + /// + /// + /// If a container application is to support context-sensitive help on menu items, it must either provide its own message filter + /// so that it can intercept the F1 key or ask the OLE library to add a message filter by calling OleSetMenuDescriptor, passing + /// valid, non-NULL values for the lpFrame and lpActiveObj parameters. + /// + /// + [PreserveSig] + new HRESULT ContextSensitiveHelp([MarshalAs(UnmanagedType.Bool)] bool fEnterMode); + + /// + /// Processes menu accelerator-key messages from the container's message queue. This method should only be used for objects + /// created by a DLL object application. + /// + /// A pointer to an MSG structure for the message that might need to be translated. + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// S_FALSE + /// The message was not translated. + /// + /// + /// E_INVALIDARG + /// The specified parameter values are not valid. + /// + /// + /// E_OUTOFMEMORY + /// IThere is insufficient memory available for the operation. + /// + /// + /// E_UNEXPECTED + /// An unexpected error has occurred. + /// + /// + /// + /// + /// Notes to Callers + /// + /// Active in-place objects must always be given the first chance at translating accelerator keystrokes. You can provide this + /// opportunity by calling IOleInPlaceActiveObject::TranslateAccelerator from your container's message loop before doing + /// any other translation. You should apply your own translation only when this method returns S_FALSE. + /// + /// + /// If you call IOleInPlaceActiveObject::TranslateAccelerator for an object that is not created by a DLL object + /// application, the default object handler returns S_FALSE. + /// + /// Notes to Implementers + /// + /// An object created by an EXE object application gets keystrokes from its own message pump, so the container does not get + /// those messages. + /// + /// If you need to implement this method, you can do so by simply wrapping the call to the TranslateAccelerator function. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplaceactiveobject-translateaccelerator HRESULT + // TranslateAccelerator( LPMSG lpmsg ); + [PreserveSig] + HRESULT TranslateAccelerator(in MSG lpmsg); + + /// Notifies the object when the container's top-level frame window is activated or deactivated. + /// + /// The state of the container's top-level frame window. This parameter is TRUE if the window is activating and + /// FALSE if it is deactivating. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplaceactiveobject-onframewindowactivate HRESULT + // OnFrameWindowActivate( BOOL fActivate ); + void OnFrameWindowActivate([MarshalAs(UnmanagedType.Bool)] bool fActivate); + + /// Notifies the active in-place object when the container's document window is activated or deactivated. + /// + /// The state of the MDI child document window. If this parameter is TRUE, the window is in the act of activating; if it + /// is FALSE, it is in the act of deactivating. + /// + /// + /// Notes to Callers + /// + /// Call IOleInPlaceActiveObject::OnDocWindowActivate when the MDI child document window is activated or deactivated and + /// the object is currently the active object for the document. + /// + /// Notes to Implementers + /// + /// You should include code in this method that installs frame-level tools during object activation. These tools include the + /// shared composite menu and/or optional toolbars and frame adornments. You should then take focus. When deactivating, the + /// object should remove the frame-level tools. Note that if you do not call IOleInPlaceUIWindow::SetBorderSpace with + /// pborderwidths set to NULL, you can avoid having to renegotiate border space. + /// + /// + /// While executing IOleInPlaceActiveObject::OnDocWindowActivate, do not make calls to the PeekMessage or GetMessage + /// functions, or a dialog box. Doing so may cause the system to deadlock. There are further restrictions on which OLE interface + /// methods and functions can be called from within IOleInPlaceActiveObject::OnDocWindowActivate. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplaceactiveobject-ondocwindowactivate HRESULT + // OnDocWindowActivate( BOOL fActivate ); + void OnDocWindowActivate([MarshalAs(UnmanagedType.Bool)] bool fActivate); + + /// Alerts the object that it needs to resize its border space. + /// + /// A pointer to a RECT structure containing the new outer rectangle within which the object can request border space for its tools. + /// + /// + /// A pointer to an IOleInPlaceUIWindow interface pointer for the frame or document window object whose border has changed. + /// + /// + /// This parameter is TRUE if the frame window object is calling IOleInPlaceActiveObject::ResizeBorder; otherwise, + /// it is FALSE. + /// + /// + /// Notes to Callers + /// + /// IOleInPlaceActiveObject::ResizeBorder is called by the top-level container's document or frame window object when the + /// border space allocated to the object should change. Because the active in-place object is not informed about which window + /// has changed (the frame- or document-level window), IOleInPlaceActiveObject::ResizeBorder must be passed the pointer + /// to the window's IOleInPlaceUIWindow interface. + /// + /// Notes to Implemeters + /// + /// In most cases, resizing only requires that you grow, shrink, or scale your object's frame adornments. However, for more + /// complicated adornments, you may be required to renegotiate for border space with calls to + /// IOleInPlaceUIWindow::SetBorderSpace and IOleInPlaceUIWindow::SetBorderSpace. + /// + /// + /// Note While executing IOleInPlaceActiveObject::ResizeBorder, do not make calls to the PeekMessage or GetMessage + /// functions, or a dialog box. Doing so may cause the system to deadlock. There are further restrictions on which OLE interface + /// methods and functions can be called from within IOleInPlaceActiveObject::ResizeBorder. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplaceactiveobject-resizeborder HRESULT + // ResizeBorder( LPCRECT prcBorder, IOleInPlaceUIWindow *pUIWindow, BOOL fFrameWindow ); + void ResizeBorder(in RECT prcBorder, [In] IOleInPlaceUIWindow pUIWindow, [MarshalAs(UnmanagedType.Bool)] bool fFrameWindow); + + /// Enables or disables modeless dialog boxes when the container creates or destroys a modal dialog box. + /// Indicates whether to enable modeless dialog box windows ( TRUE) or disable them FALSE. + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplaceactiveobject-enablemodeless HRESULT + // EnableModeless( BOOL fEnable ); + void EnableModeless([MarshalAs(UnmanagedType.Bool)] bool fEnable); + } + + /// + /// Controls the container's top-level frame window. This control involves allowing the container to insert its menu group into the + /// composite menu, install the composite menu into the appropriate window frame, and remove the container's menu elements from the + /// composite menu. It sets and displays status text relevant to the in-place object. It also enables or disables the frame's + /// modeless dialog boxes, and translates accelerator keystrokes intended for the container's frame. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nn-oleidl-ioleinplaceframe + [PInvokeData("oleidl.h", MSDNShortId = "c530aff7-fd83-413d-8945-0c9d1bfb51ba")] + [ComImport, Guid("00000116-0000-0000-C000-000000000046"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IOleInPlaceFrame : IOleInPlaceUIWindow + { + /// + /// Retrieves a handle to one of the windows participating in in-place activation (frame, document, parent, or in-place object window). + /// + /// A pointer to a variable that receives the window handle. + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// E_FAIL + /// The object is windowless. + /// + /// + /// E_OUTOFMEMORY + /// There is insufficient memory available for this operation. + /// + /// + /// E_UNEXPECTED + /// An unexpected error has occurred. + /// + /// + /// + /// + /// + /// Five types of windows comprise the windows hierarchy. When a object is active in place, it has access to some or all of + /// these windows. + /// + /// + /// + /// Window + /// Description + /// + /// + /// Frame + /// The outermost main window where the container application's main menu resides. + /// + /// + /// Document + /// The window that displays the compound document containing the embedded object to the user. + /// + /// + /// Pane + /// + /// The subwindow of the document window that contains the object's view. Applicable only for applications with split-pane windows. + /// + /// + /// + /// Parent + /// + /// The container window that contains that object's view. The object application installs its window as a child of this window. + /// + /// + /// + /// In-place + /// + /// The window containing the active in-place object. The object application creates this window and installs it as a child of + /// its hatch window, which is a child of the container's parent window. + /// + /// + /// + /// + /// Each type of window has a different role in the in-place activation architecture. However, it is not necessary to employ a + /// separate physical window for each type. Many container applications use the same window for their frame, document, pane, and + /// parent windows. + /// + /// + [PreserveSig] + new HRESULT GetWindow(out HWND phwnd); + + /// Determines whether context-sensitive help mode should be entered during an in-place activation session. + /// + /// if help mode should be entered; if it should be exited. + /// + /// + /// + /// This method returns S_OK if the help mode was entered or exited successfully, depending on the value passed in . Other possible return values include the following.
+ /// + /// + /// + /// Return code + /// Description + /// + /// + /// E_INVALIDARG + /// The specified value is not valid. + /// + /// + /// E_OUTOFMEMORY + /// There is insufficient memory available for this operation. + /// + /// + /// E_UNEXPECTED + /// An unexpected error has occurred. + /// + /// + /// + /// + /// Applications can invoke context-sensitive help when the user: + /// + /// presses SHIFT+F1, then clicks a topic + /// presses F1 when a menu item is selected + /// + /// + /// When SHIFT+F1 is pressed, either the frame or active object can receive the keystrokes. If the container's frame receives + /// the keystrokes, it calls its containing document's IOleWindow::ContextSensitiveHelp method with set to . This propagates the help state to all of its in-place objects so they can + /// correctly handle the mouse click or WM_COMMAND. + /// + /// + /// If an active object receives the SHIFT+F1 keystrokes, it calls the container's IOleWindow::ContextSensitiveHelp method with + /// set to , which then recursively calls each of its in-place sites until + /// there are no more to be notified. The container then calls its document's or frame's IOleWindow::ContextSensitiveHelp method + /// with set to . + /// + /// When in context-sensitive help mode, an object that receives the mouse click can either: + /// + /// Ignore the click if it does not support context-sensitive help. + /// + /// Tell all the other objects to exit context-sensitive help mode with ContextSensitiveHelp set to FALSE and then provide help + /// for that context. + /// + /// + /// + /// An object in context-sensitive help mode that receives a WM_COMMAND should tell all the other in-place objects to exit + /// context-sensitive help mode and then provide help for the command. + /// + /// + /// If a container application is to support context-sensitive help on menu items, it must either provide its own message filter + /// so that it can intercept the F1 key or ask the OLE library to add a message filter by calling OleSetMenuDescriptor, passing + /// valid, non-NULL values for the lpFrame and lpActiveObj parameters. + /// + /// + [PreserveSig] + new HRESULT ContextSensitiveHelp([MarshalAs(UnmanagedType.Bool)] bool fEnterMode); + + /// Retrieves the outer rectange for toolbars and controls while the object is active in place. + /// + /// A pointer to a RECT structure where the outer rectangle is to be returned. The structure's coordinates are relative to the + /// window being represented by the interface. + /// + /// + /// Notes to Callers + /// + /// The IOleInPlaceUIWindow::GetBorder function, when called on a document or frame window object, returns the outer + /// rectangle (relative to the window) where the object can put toolbars or similar controls. + /// + /// + /// If the object is to install these tools, it should negotiate space for the tools within this rectangle using + /// IOleInPlaceUIWindow::RequestBorderSpace and then call IOleInPlaceUIWindow::SetBorderSpace to get this space allocated. + /// + /// + /// Note While executing IOleInPlaceUIWindow::GetBorder, do not make calls to the PeekMessage or GetMessage + /// functions, or a dialog box. Doing so may cause the system to deadlock. There are further restrictions on which OLE interface + /// methods and functions can be called from within GetBorder. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplaceuiwindow-getborder HRESULT GetBorder( LPRECT + // lprectBorder ); + new void GetBorder(out RECT lprectBorder); + + /// + /// Determines whether there is space available for tools to be installed around the object's window frame while the object is + /// active in place. + /// + /// + /// A pointer to a BORDERWIDTHS structure containing the requested widths (in pixels) needed on each side of the window for the tools. + /// + /// + /// Notes to Callers + /// + /// The active in-place object calls IOleInPlaceUIWindow::RequestBorderSpace to ask if tools can be installed inside the + /// window frame. These tools would be allocated between the rectangle returned by IOleInPlaceUIWindow::GetBorder and the + /// BORDERWIDTHS structure specified in the argument to this call. + /// + /// + /// The space for the tools is not actually allocated to the object until it calls IOleInPlaceUIWindow::SetBorderSpace, allowing + /// the object to negotiate for space (such as while dragging toolbars around), but deferring the moving of tools until the + /// action is completed. + /// + /// + /// The object can install these tools by passing the width in pixels that is to be used on each side. For example, if the + /// object required 10 pixels on the top, 0 pixels on the bottom, and 5 pixels on the left and right sides, it would pass the + /// following BORDERWIDTHS structure to IOleInPlaceUIWindow::RequestBorderSpace: + /// + /// + /// Note While executing IOleInPlaceUIWindow::RequestBorderSpace, do not make calls to the PeekMessage or + /// GetMessage functions, or a dialog box. Doing so may cause the system to deadlock. There are further restrictions on which + /// OLE interface methods and functions can be called from within IOleInPlaceUIWindow::RequestBorderSpace. + /// + /// Notes to Implementers + /// + /// If the amount of space an active object uses for its toolbars is irrelevant to the container, it can simply return NOERROR + /// as shown in the following IOleInPlaceUIWindow::RequestBorderSpace example. Containers should not unduly restrict the + /// display of tools by an active in-place object. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplaceuiwindow-requestborderspace HRESULT + // RequestBorderSpace( LPCBORDERWIDTHS pborderwidths ); + new void RequestBorderSpace(in RECT pborderwidths); + + /// Allocates space for the border requested in the call to IOleInPlaceUIWindow::RequestBorderSpace. + /// + /// Pointer to a BORDERWIDTHS structure containing the requested width of the tools, in pixels. It can be NULL, + /// indicating the object does not need any space. + /// + /// + /// The object must call IOleInPlaceUIWindow::SetBorderSpace. It can do any one of the following: + /// + /// + /// Use its own toolbars, requesting border space of a specific size. + /// + /// + /// + /// Use no toolbars, but force the container to remove its toolbars by passing a valid BORDERWIDTHS structure containing nothing + /// but zeros in the pborderwidths parameter. + /// + /// + /// + /// + /// Use no toolbars but allow the in-place container to leave its toolbars up by passing NULL as the pborderwidths parameter. + /// + /// + /// + /// + /// The BORDERWIDTHS structure used in this call would generally have been passed in a previous call to + /// IOleInPlaceUIWindow::RequestBorderSpace, which must have returned S_OK. + /// + /// + /// If an object must renegotiate space on the border, it can call IOleInPlaceUIWindow::SetBorderSpace again with the new + /// widths. If the call to IOleInPlaceUIWindow::SetBorderSpace fails, the object can do a full negotiation for border + /// space with calls to IOleInPlaceUIWindow::GetBorder, IOleInPlaceUIWindow::RequestBorderSpace, and IOleInPlaceUIWindow::SetBorderSpace. + /// + /// + /// Note While executing IOleInPlaceUIWindow::SetBorderSpace, do not make calls to the PeekMessage or GetMessage + /// functions, or a dialog box. Doing so may cause the system to deadlock. There are further restrictions on which OLE interface + /// methods and functions can be called from within IOleInPlaceUIWindow::SetBorderSpace. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplaceuiwindow-setborderspace HRESULT + // SetBorderSpace( LPCBORDERWIDTHS pborderwidths ); + new void SetBorderSpace(in RECT pborderwidths); + + /// Provides a direct channel of communication between the object and each of the frame and document windows. + /// A pointer to the IOleInPlaceActiveObject interface on the active in-place object. + /// + /// A pointer to a string containing a name that describes the object an embedding container can use in composing its window + /// title. It can be NULL if the object does not require the container to change its window titles. Containers should + /// ignore this parameter and always use their own name in the title bar. + /// + /// + /// + /// Generally, an embedded object should pass NULL for the pszObjName parameter (see Notes to Implementers below). + /// However, if you are working in conjunction with a container that does display the name of the in-place active object in its + /// title bar, then you should compose a string in the following form: <application name> – <object short-type name>. + /// + /// Notes to Callers + /// + /// IOleInPlaceUIWindow::SetActiveObject is called by the object to establish a direct communication link between itself + /// and the document and frame windows. + /// + /// + /// When deactivating, the object calls IOleInPlaceUIWindow::SetActiveObject, passing NULL for the pActiveObject + /// and pszObjName parameters. + /// + /// + /// An object must call IOleInPlaceUIWindow::SetActiveObject before calling IOleInPlaceFrame::SetMenu to give the + /// container the pointer to the active object. The container then uses this pointer in processing + /// IOleInPlaceFrame::SetMenu and to pass to OleSetMenuDescriptor. + /// + /// Notes to Implementers + /// + /// The Microsoft Windows User Interface Design Guide recommends that an in-place container ignore the pszObjName parameter + /// passed in this method. The guide says "The title bar is not affected by in-place activation. It always displays the + /// top-level container's name." + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplaceuiwindow-setactiveobject HRESULT + // SetActiveObject( IOleInPlaceActiveObject *pActiveObject, LPCOLESTR pszObjName ); + new void SetActiveObject([In] IOleInPlaceActiveObject pActiveObject, [MarshalAs(UnmanagedType.LPWStr)] string pszObjName); + + /// Enables the container to insert menu groups into the composite menu to be used during the in-place session. + /// A handle to an empty menu. + /// + /// A pointer to an OLEMENUGROUPWIDTHS array with six elements. The container fills in elements 0, 2, and 4 to reflect the + /// number of menu elements it provided in the File, View, and Window menu groups. + /// + /// + /// Notes to Callers + /// + /// This method is called by object applications when they are first being activated. They call it to insert their menus into + /// the frame-level user interface. + /// + /// + /// The object application asks the container to add its menus to the menu specified in hmenuShared and to set the group counts + /// in the OLEMENUGROUPWIDTHS array pointed to by lpMenuWidths. The object application then adds its own menus and counts. + /// Objects can call IOleInPlaceFrame::InsertMenus as many times as necessary to build up the composite menus. The + /// container should use the initial menu handle associated with the composite menu for all menu items in the drop-down menus. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplaceframe-insertmenus HRESULT InsertMenus( HMENU + // hmenuShared, LPOLEMENUGROUPWIDTHS lpMenuWidths ); + void InsertMenus(HMENU hmenuShared, ref OLEMENUGROUPWIDTHS lpMenuWidths); + + /// Adds a composite menu to the window frame containing the object being activated in place. + /// + /// A handle to the composite menu constructed by calls to IOleInPlaceFrame::InsertMenus and the InsertMenu function. + /// + /// A handle to the menu descriptor returned by the OleCreateMenuDescriptor function. + /// + /// A handle to a window owned by the object and to which menu messages, commands, and accelerators are to be sent. + /// + /// + /// Notes to Callers + /// + /// The object calls IOleInPlaceFrame::SetMenu to ask the container to install the composite menu structure set up by + /// calls to IOleInPlaceFrame::InsertMenus. + /// + /// Notes to Implementers + /// + /// An SDI container's implementation of this method should call the SetMenu function. An MDI container should send a + /// WM_MDISETMENU message, using hmenuShared as the menu to install. The container should call OleSetMenuDescriptor to install + /// the OLE dispatching code. + /// + /// + /// When deactivating, the container must call IOleInPlaceFrame::SetMenu, specifying NULL to remove the shared + /// menu. This is done to help minimize window repaints. The container should also call OleSetMenuDescriptor, specifying + /// NULL to unhook the dispatching code. Finally, the object application calls OleDestroyMenuDescriptor to free the data structure. + /// + /// + /// Note While executing IOleInPlaceFrame::SetMenu, do not make calls to the PeekMessage or GetMessage functions, + /// or a dialog box. Doing so may cause the system to deadlock. There are further restrictions on which OLE interface methods + /// and functions can be called from within IOleInPlaceFrame::SetMenu. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplaceframe-setmenu HRESULT SetMenu( HMENU + // hmenuShared, HOLEMENU holemenu, HWND hwndActiveObject ); + void SetMenu(HMENU hmenuShared, HOLEMENU holemenu, HWND hwndActiveObject); + + /// Removes a container's menu elements from the composite menu. + /// + /// A handle to the in-place composite menu that was constructed by calls to IOleInPlaceFrame::InsertMenus and the InsertMenu function. + /// + /// + /// + /// The object should always give the container a chance to remove its menu elements from the composite menu before deactivating + /// the shared user interface. + /// + /// Notes to Callers + /// This method is called by the object application while it is being UI-deactivated to remove its menus. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplaceframe-removemenus HRESULT RemoveMenus( HMENU + // hmenuShared ); + void RemoveMenus(HMENU hmenuShared); + + /// Sets and displays status text about the in-place object in the container's frame window status line. + /// The message to be displayed. + /// + /// Notes to Callers + /// + /// You should call IOleInPlaceFrame::SetStatusText when you need to ask the container to display object text in its + /// frame's status line, if it has one. Because the container's frame window owns the status line, calling + /// IOleInPlaceFrame::SetStatusText is the only way an object can display status information in the container's frame + /// window. If the container refuses the object's request, the object application can, however, negotiate for border space to + /// display its own status window. + /// + /// + /// When switching between menus owned by the container and the in-place active object, the status bar text is not reflected + /// properly if the object does not call the container's IOleInPlaceFrame::SetStatusText method. For example, if, during + /// an in-place session, the user were to select the File menu, the status bar would reflect the action that would occur + /// if the user selected this menu. If the user then selects the Edit menu (which is owned by the in-place object), the + /// status bar text would not change unless the IOleInPlaceFrame::SetStatusText happened to be called. This is because + /// there is no way for the container to recognize that one of the object's menus has been made active because all the messages + /// that the container would trap are now going to the object. + /// + /// Notes to Implementers + /// + /// To avoid potential problems, all objects being activated in place should process the WM_MENUSELECT message and call + /// IOleInPlaceFrame::SetStatusText —even if the object does not usually provide status information (in which case the + /// object can just pass a NULL string for the requested status text). + /// + /// + /// Note While executing IOleInPlaceFrame::SetStatusText, do not make calls to the PeekMessage or GetMessage + /// functions, or a dialog box. Doing so may cause the system to deadlock. There are further restrictions on which OLE interface + /// methods and functions can be called from within IOleInPlaceUIWindow::GetBorder. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplaceframe-setstatustext HRESULT SetStatusText( + // LPCOLESTR pszStatusText ); + void SetStatusText([MarshalAs(UnmanagedType.LPWStr)] string pszStatusText); + + /// Enables or disables a frame's modeless dialog boxes. + /// + /// Specifies whether the modeless dialog box windows are to be enabled ( TRUE) or disabled ( FALSE). + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplaceframe-enablemodeless HRESULT EnableModeless( + // BOOL fEnable ); + void EnableModeless([MarshalAs(UnmanagedType.Bool)] bool fEnable); + + /// Translates accelerator keystrokes intended for the container's frame while an object is active in place. + /// A pointer to the MSG structure that contains the keystroke message. + /// + /// The command identifier value corresponding to the keystroke in the container-provided accelerator table. Containers should + /// use this value instead of translating again. + /// + /// + /// Notes to Callers + /// + /// The IOleInPlaceFrame::TranslateAccelerator method is called indirectly by OleTranslateAccelerator when a keystroke + /// accelerator intended for the container (frame) is received. + /// + /// Notes to Implementers + /// + /// The container application should perform its usual accelerator processing, or use wID directly, and then return, indicating + /// whether the keystroke accelerator was processed. If the container is an MDI application and the TranslateAccelerator + /// function fails, the container can call the TranslateMDISysAccel function, just as it does for its usual message processing. + /// + /// + /// In-place objects should be given first chance at translating accelerator messages. However, because objects implemented by + /// DLL object applications do not have their own message pump, they receive their messages from the container's message queue. + /// To ensure that the object has first chance at translating messages, a container should always call + /// IOleInPlaceFrame::TranslateAccelerator before doing its own accelerator translation. Conversely, an executable object + /// application should call OleTranslateAccelerator after calling TranslateAccelerator, calling TranslateMessage and + /// DispatchMessage only if both translation functions fail. + /// + /// + /// You should define accelerator tables for containers so they will work properly with object applications that do their own + /// accelerator keystroke translations. Tables should be defined as follows. + /// + /// + /// This is the most common way to describe keyboard accelerators. Failure to do so can result in keystrokes being lost or sent + /// to the wrong object during an in-place session. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplaceframe-translateaccelerator HRESULT + // TranslateAccelerator( LPMSG lpmsg, WORD wID ); + void TranslateAccelerator(in MSG lpmsg, in ushort wID); + } + + /// + /// + /// Manages the activation and deactivation of in-place objects, and determines how much of the in-place object should be visible. + /// + /// You can obtain a pointer to IOleInPlaceObject by calling IUnknown::QueryInterface on IOleObject. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nn-oleidl-ioleinplaceobject + [PInvokeData("oleidl.h", MSDNShortId = "NN:oleidl.IOleInPlaceObject")] + [ComImport, Guid("00000113-0000-0000-C000-000000000046"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IOleInPlaceObject : IOleWindow + { + /// + /// Retrieves a handle to one of the windows participating in in-place activation (frame, document, parent, or in-place object window). + /// + /// A pointer to a variable that receives the window handle. + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// E_FAIL + /// The object is windowless. + /// + /// + /// E_OUTOFMEMORY + /// There is insufficient memory available for this operation. + /// + /// + /// E_UNEXPECTED + /// An unexpected error has occurred. + /// + /// + /// + /// + /// + /// Five types of windows comprise the windows hierarchy. When a object is active in place, it has access to some or all of + /// these windows. + /// + /// + /// + /// Window + /// Description + /// + /// + /// Frame + /// The outermost main window where the container application's main menu resides. + /// + /// + /// Document + /// The window that displays the compound document containing the embedded object to the user. + /// + /// + /// Pane + /// + /// The subwindow of the document window that contains the object's view. Applicable only for applications with split-pane windows. + /// + /// + /// + /// Parent + /// + /// The container window that contains that object's view. The object application installs its window as a child of this window. + /// + /// + /// + /// In-place + /// + /// The window containing the active in-place object. The object application creates this window and installs it as a child of + /// its hatch window, which is a child of the container's parent window. + /// + /// + /// + /// + /// Each type of window has a different role in the in-place activation architecture. However, it is not necessary to employ a + /// separate physical window for each type. Many container applications use the same window for their frame, document, pane, and + /// parent windows. + /// + /// + [PreserveSig] + new HRESULT GetWindow(out HWND phwnd); + + /// Determines whether context-sensitive help mode should be entered during an in-place activation session. + /// + /// if help mode should be entered; if it should be exited. + /// + /// + /// + /// This method returns S_OK if the help mode was entered or exited successfully, depending on the value passed in . Other possible return values include the following.
+ /// + /// + /// + /// Return code + /// Description + /// + /// + /// E_INVALIDARG + /// The specified value is not valid. + /// + /// + /// E_OUTOFMEMORY + /// There is insufficient memory available for this operation. + /// + /// + /// E_UNEXPECTED + /// An unexpected error has occurred. + /// + /// + /// + /// + /// Applications can invoke context-sensitive help when the user: + /// + /// presses SHIFT+F1, then clicks a topic + /// presses F1 when a menu item is selected + /// + /// + /// When SHIFT+F1 is pressed, either the frame or active object can receive the keystrokes. If the container's frame receives + /// the keystrokes, it calls its containing document's IOleWindow::ContextSensitiveHelp method with set to . This propagates the help state to all of its in-place objects so they can + /// correctly handle the mouse click or WM_COMMAND. + /// + /// + /// If an active object receives the SHIFT+F1 keystrokes, it calls the container's IOleWindow::ContextSensitiveHelp method with + /// set to , which then recursively calls each of its in-place sites until + /// there are no more to be notified. The container then calls its document's or frame's IOleWindow::ContextSensitiveHelp method + /// with set to . + /// + /// When in context-sensitive help mode, an object that receives the mouse click can either: + /// + /// Ignore the click if it does not support context-sensitive help. + /// + /// Tell all the other objects to exit context-sensitive help mode with ContextSensitiveHelp set to FALSE and then provide help + /// for that context. + /// + /// + /// + /// An object in context-sensitive help mode that receives a WM_COMMAND should tell all the other in-place objects to exit + /// context-sensitive help mode and then provide help for the command. + /// + /// + /// If a container application is to support context-sensitive help on menu items, it must either provide its own message filter + /// so that it can intercept the F1 key or ask the OLE library to add a message filter by calling OleSetMenuDescriptor, passing + /// valid, non-NULL values for the lpFrame and lpActiveObj parameters. + /// + /// + [PreserveSig] + new HRESULT ContextSensitiveHelp([MarshalAs(UnmanagedType.Bool)] bool fEnterMode); + + /// Deactivates an active in-place object and discards the object's undo state. + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// E_UNEXPECTED + /// An unexpected error occurred. + /// + /// + /// + /// + /// Notes to Callers + /// + /// This method is called by an active object's immediate container to deactivate the active object and discard its undo state. + /// + /// Notes to Implementers + /// + /// On return from IOleInPlaceObject::InPlaceDeactivate, the object discards its undo state. The object application + /// should not shut down immediately after this call. Instead, it should wait for an explicit call to IOleObject::Close or for + /// the object's reference count to reach zero. + /// + /// + /// Before deactivating, the object application should give the container a chance to put its user interface back on the frame + /// window by calling IOleInPlaceSite::OnUIDeactivate. + /// + /// + /// If the in-place user interface is still visible during the call to IOleInPlaceObject::InPlaceDeactivate, the object + /// application should call its own IOleInPlaceObject::InPlaceDeactivate method to hide the user interface. The in-place + /// user interface can be optionally destroyed during calls to IOleInPlaceObject::InPlaceDeactivate and + /// IOleInPlaceObject::InPlaceDeactivate. But if the user interface has not already been destroyed when the container + /// calls IOleObject::Close, then it must be destroyed during the call to IOleObject::Close. + /// + /// + /// During the call to IOleObject::Close, the object should check to see whether it is still active in place. If so, it should + /// call IOleInPlaceObject::InPlaceDeactivate. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplaceobject-inplacedeactivate HRESULT InPlaceDeactivate(); + [PreserveSig] + HRESULT InPlaceDeactivate(); + + /// Deactivates and removes the user interface of an active in-place object. + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// E_UNEXPECTED + /// An unexpected error has occurred. + /// + /// + /// + /// + /// Notes to Callers + /// + /// This method is called by the object's immediate container when, for example, the user has clicked in the client area outside + /// the object. + /// + /// + /// If the container has called IOleInPlaceObject::UIDeactivate, it should later call + /// IOleInPlaceObject::InPlaceDeactivate to properly clean up resources. The container can assume that stopping or releasing the + /// object cleans up resources if necessary. The object must be prepared to do so if IOleInPlaceObject::InPlaceDeactivate + /// has not been called. but either IOleInPlaceObject::UIDeactivate or IOleObject::Close has been called. + /// + /// Notes to Implementers + /// + /// Resources such as menus and windows can be either cleaned up or kept in a hidden state until your object is completely + /// deactivated by calls to either IOleInPlaceObject::InPlaceDeactivate or IOleObject::Close. The object application must call + /// IOleInPlaceSite::OnUIDeactivate before doing anything with the composite menus so that the container can first be detached + /// from the frame window. On deactivating the in-place object's user interface, the object is left in a ready state so it can + /// be quickly reactivated. The object stays in this state until the undo state of the document changes. The container should + /// then call IOleInPlaceObject::InPlaceDeactivate to tell the object to discard its undo state. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplaceobject-uideactivate HRESULT UIDeactivate(); + [PreserveSig] + HRESULT UIDeactivate(); + + /// Specifies how much of the in-place object is to be visible. + /// + /// A pointer to the RECT structure containing the position of the in-place object using the client coordinates of its parent window. + /// + /// + /// A pointer to the outer rectangle containing the in-place object's position rectangle (lprcPosRect). This rectangle is + /// relative to the client area of the object's parent window. + /// + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// E_INVALIDARG + /// The specified pointer is invalid. + /// + /// + /// E_OUTOFMEMORY + /// There is insufficient memory available for the operation. + /// + /// + /// E_UNEXPECTED + /// An unexpected error has occurred. + /// + /// + /// + /// + /// It is possible for lprcClipRect to change without lprcPosRect changing. + /// + /// The size of an in-place object's rectangle is always calculated in pixels. This is different from other OLE object's + /// visualizations, which are in HIMETRIC. + /// + /// + /// Note While executing IOleInPlaceObject::SetObjectRects, do not make calls to the PeekMessage or GetMessage + /// functions, or a dialog box. Doing so may cause the system to deadlock. There are further restrictions on which OLE interface + /// methods and functions can be called from within IOleInPlaceObject::SetObjectRects. + /// + /// Notes to Callers + /// + /// The container should call IOleInPlaceObject::SetObjectRects whenever the window position of the in-place object + /// and/or the visible part of the in-place object changes. + /// + /// Notes to Implementers + /// + /// The object must size its in-place window to match the intersection of lprcPosRect and lprcClipRect. The object must also + /// draw its contents into the object's in-place window so that proper clipping takes place. + /// + /// + /// The object should compare its width and height with those provided by its container (conveyed through lprcPosRect). If the + /// comparison does not result in a match, the container is applying scaling to the object. The object must then decide whether + /// it should continue the in-place editing in the scale/zoom mode or deactivate. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplaceobject-setobjectrects HRESULT SetObjectRects( + // LPCRECT lprcPosRect, LPCRECT lprcClipRect ); + [PreserveSig] + HRESULT SetObjectRects(in RECT lprcPosRect, in RECT lprcClipRect); + + /// Reactivates a previously deactivated object, undoing the last state of the object. + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// E_NOTUNDOABLE + /// The undo state is not available. + /// + /// + /// E_OUTOFMEMORY + /// There is insufficient memory available for the operation. + /// + /// + /// E_UNEXPECTED + /// An unexpected error has occurred. + /// + /// + /// + /// + /// If the user chooses the Undo command before the undo state of the object is lost, the object's immediate container + /// calls IOleInPlaceObject::ReactivateAndUndo to activate the user interface, carry out the undo operation, and return + /// the object to the active state. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplaceobject-reactivateandundo HRESULT ReactivateAndUndo(); + [PreserveSig] + HRESULT ReactivateAndUndo(); + } + + /// + /// + /// Manages the interaction between the container and the object's in-place client site. Recall that the client site is the display + /// site for embedded objects, and provides position and conceptual information about the object. + /// + /// + /// This interface provides methods that manage in-place objects. With IOleInPlaceSite, you can determine if an object can be + /// activated and manage its activation and deactivation. You can notify the container when one of its objects is being activated + /// and inform the container that a composite menu will replace the container's regular menu. It provides methods that make it + /// possible for the in-place object to retrieve the window object hierarchy, and the position in the parent window where the object + /// should place its in-place activation window. Finally, it determines how the container scrolls the object, manages the object + /// undo state, and notifies the object when its borders have changed. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nn-oleidl-ioleinplacesite + [PInvokeData("oleidl.h", MSDNShortId = "NN:oleidl.IOleInPlaceSite")] + [ComImport, Guid("00000119-0000-0000-C000-000000000046"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IOleInPlaceSite : IOleWindow + { + /// + /// Retrieves a handle to one of the windows participating in in-place activation (frame, document, parent, or in-place object window). + /// + /// A pointer to a variable that receives the window handle. + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// E_FAIL + /// The object is windowless. + /// + /// + /// E_OUTOFMEMORY + /// There is insufficient memory available for this operation. + /// + /// + /// E_UNEXPECTED + /// An unexpected error has occurred. + /// + /// + /// + /// + /// + /// Five types of windows comprise the windows hierarchy. When a object is active in place, it has access to some or all of + /// these windows. + /// + /// + /// + /// Window + /// Description + /// + /// + /// Frame + /// The outermost main window where the container application's main menu resides. + /// + /// + /// Document + /// The window that displays the compound document containing the embedded object to the user. + /// + /// + /// Pane + /// + /// The subwindow of the document window that contains the object's view. Applicable only for applications with split-pane windows. + /// + /// + /// + /// Parent + /// + /// The container window that contains that object's view. The object application installs its window as a child of this window. + /// + /// + /// + /// In-place + /// + /// The window containing the active in-place object. The object application creates this window and installs it as a child of + /// its hatch window, which is a child of the container's parent window. + /// + /// + /// + /// + /// Each type of window has a different role in the in-place activation architecture. However, it is not necessary to employ a + /// separate physical window for each type. Many container applications use the same window for their frame, document, pane, and + /// parent windows. + /// + /// + [PreserveSig] + new HRESULT GetWindow(out HWND phwnd); + + /// Determines whether context-sensitive help mode should be entered during an in-place activation session. + /// + /// if help mode should be entered; if it should be exited. + /// + /// + /// + /// This method returns S_OK if the help mode was entered or exited successfully, depending on the value passed in . Other possible return values include the following.
+ /// + /// + /// + /// Return code + /// Description + /// + /// + /// E_INVALIDARG + /// The specified value is not valid. + /// + /// + /// E_OUTOFMEMORY + /// There is insufficient memory available for this operation. + /// + /// + /// E_UNEXPECTED + /// An unexpected error has occurred. + /// + /// + /// + /// + /// Applications can invoke context-sensitive help when the user: + /// + /// presses SHIFT+F1, then clicks a topic + /// presses F1 when a menu item is selected + /// + /// + /// When SHIFT+F1 is pressed, either the frame or active object can receive the keystrokes. If the container's frame receives + /// the keystrokes, it calls its containing document's IOleWindow::ContextSensitiveHelp method with set to . This propagates the help state to all of its in-place objects so they can + /// correctly handle the mouse click or WM_COMMAND. + /// + /// + /// If an active object receives the SHIFT+F1 keystrokes, it calls the container's IOleWindow::ContextSensitiveHelp method with + /// set to , which then recursively calls each of its in-place sites until + /// there are no more to be notified. The container then calls its document's or frame's IOleWindow::ContextSensitiveHelp method + /// with set to . + /// + /// When in context-sensitive help mode, an object that receives the mouse click can either: + /// + /// Ignore the click if it does not support context-sensitive help. + /// + /// Tell all the other objects to exit context-sensitive help mode with ContextSensitiveHelp set to FALSE and then provide help + /// for that context. + /// + /// + /// + /// An object in context-sensitive help mode that receives a WM_COMMAND should tell all the other in-place objects to exit + /// context-sensitive help mode and then provide help for the command. + /// + /// + /// If a container application is to support context-sensitive help on menu items, it must either provide its own message filter + /// so that it can intercept the F1 key or ask the OLE library to add a message filter by calling OleSetMenuDescriptor, passing + /// valid, non-NULL values for the lpFrame and lpActiveObj parameters. + /// + /// + [PreserveSig] + new HRESULT ContextSensitiveHelp([MarshalAs(UnmanagedType.Bool)] bool fEnterMode); + + /// Determines whether the container can activate the object in place. + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// S_FALSE + /// The container does not allow in-place activation for this object. + /// + /// + /// E_UNEXPECTED + /// An unexpected error has occurred. + /// + /// + /// + /// + /// Only objects being displayed as DVASPECT_CONTENT can be activated in place. + /// Notes to Callers + /// + /// CanInPlaceActivate is called by the client site's immediate child object when this object must activate in place. + /// This function allows the container application to accept or refuse the activation request. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplacesite-caninplaceactivate HRESULT CanInPlaceActivate(); + [PreserveSig] + HRESULT CanInPlaceActivate(); + + /// Notifies the container that one of its objects is being activated in place. + /// + /// + /// This method returns S_OK if the container allows the in-place activation. Other possible return values include the following. + /// + /// + /// + /// Return code + /// Description + /// + /// + /// E_UNEXPECTED + /// An unexpected error has occurred. + /// + /// + /// + /// + /// Notes to Callers + /// + /// OnInPlaceActivate is called by the active embedded object when it is activated in-place for the first time. The + /// container should note that the object is becoming active. + /// + /// Notes to Implementers + /// + /// A container that supports linking to embedded objects must properly manage the running of its in-place objects when they are + /// UI-inactive and running in the hidden state. To reactivate the in-place object quickly, a container should not call + /// IOleObject::Close until the container's IOleInPlaceSite::DeactivateAndUndo method is called. To help protect against the + /// object being left in an unstable state if a linking client updates silently, the container should call OleLockRunning to + /// lock the object in the running state. This prevents the hidden in-place object from shutting down before it can be saved in + /// its container. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplacesite-oninplaceactivate HRESULT OnInPlaceActivate(); + [PreserveSig] + HRESULT OnInPlaceActivate(); + + /// + /// Notifies the container that the object is about to be activated in place and that the object is going to replace the + /// container's main menu with an in-place composite menu. + /// + /// + /// + /// This method returns S_OK if the container allows the in-place activation. Other possible return values include the following. + /// + /// + /// + /// Return code + /// Description + /// + /// + /// E_UNEXPECTED + /// An unexpected error has occurred. + /// + /// + /// + /// + /// Notes to Callers + /// The in-place object calls IOleInPlaceSite::OnUIActivate just before activating its user interface. + /// Notes to Implementers + /// + /// The container should remove any user interface associated with its own activation. If the container is itself an embedded + /// object, it should remove its document-level user interface. + /// + /// + /// If there is already an object active in place in the same document, the container should call + /// IOleInPlaceObject::UIDeactivate before calling OnUIDeactivate. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplacesite-onuiactivate HRESULT OnUIActivate(); + [PreserveSig] + HRESULT OnUIActivate(); + + /// + /// Enables an in-place object to retrieve the window interfaces that form the window object hierarchy, and the position in the + /// parent window where the object's in-place activation window should be located. + /// + /// + /// A pointer to an IOleInPlaceFrame pointer variable that receives the interface pointer to the frame. If an error occurs, the + /// implementation must set ppFrame to NULL. + /// + /// + /// A pointer to an IOleInPlaceUIWindow pointer variable that receives the interface pointer to the document window. If the + /// document window is the same as the frame window, ppDoc is set to NULL. In this case, the object can only use ppFrame + /// or border negotiation. If an error is returned, the implementation must set ppDoc to NULL. + /// + /// + /// A pointer to a RECT structure for the rectangle containing the position of the in-place object in the client coordinates of + /// its parent window. If an error is returned, this parameter must be set to NULL. + /// + /// + /// A pointer to a RECT structure for the outer rectangle containing the in-place object's position rectangle (lprcPosRect). + /// This rectangle is relative to the client area of the object's parent window. If an error is returned, this parameter must be + /// set to NULL. + /// + /// + /// A pointer to an OLEINPLACEFRAMEINFO structure the container is to fill in with appropriate data. If an error is returned, + /// this parameter must be set to NULL. + /// + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// E_INVALIDARG + /// One or more of the supplied pointers is invalid. + /// + /// + /// E_UNEXPECTED + /// An unexpected error has occurred. + /// + /// + /// + /// + /// + /// The OLEINPLACEFRAMEINFO structure provides data needed by OLE to dispatch keystroke accelerators to a container frame while + /// an object is active in place. + /// + /// + /// When an object is activated, it calls GetWindowContext from its container. The container returns the handle to its + /// in-place accelerator table through the OLEINPLACEFRAMEINFO structure. Before calling GetWindowContext, the object + /// must provide the size of the OLEINPLACEFRAMEINFO structure by filling in the cb member, pointed to by lpFrameInfo. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplacesite-getwindowcontext HRESULT + // GetWindowContext( IOleInPlaceFrame **ppFrame, IOleInPlaceUIWindow **ppDoc, LPRECT lprcPosRect, LPRECT lprcClipRect, + // LPOLEINPLACEFRAMEINFO lpFrameInfo ); + [PreserveSig] + unsafe HRESULT GetWindowContext(out IOleInPlaceFrame ppFrame, out IOleInPlaceUIWindow ppDoc, [Out] RECT* lprcPosRect, [Out] RECT* lprcClipRect, [Out] OLEINPLACEFRAMEINFO* lpFrameInfo); + + /// Instructs the container to scroll the view of the object by the specified number of pixels. + /// The number of pixels by which to scroll in the X and Y directions. + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// E_INVALIDARG + /// The specified pointer is not valid. + /// + /// + /// E_UNEXPECTED + /// An unexpected error has occurred. + /// + /// + /// + /// + /// + /// As a result of scrolling, the object's visible rectangle can change. If that happens, the container should give the new + /// clipping rectangle to the object by calling IOleInPlaceObject::SetObjectRects. The intersection of the lprcClipRect and + /// lprcPosRect rectangles gives the new visible rectangle. See IOleInPlaceSite::GetWindowContext for more information. + /// + /// Notes to Callers + /// Called by an active, in-place object when it is asking the container to scroll. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplacesite-scroll HRESULT Scroll( SIZE scrollExtant ); + [PreserveSig] + HRESULT Scroll(SIZE scrollExtant); + + /// + /// Notifies the container that it should reinstall its user interface and take focus, and whether the object has an undoable state. + /// + /// Specifies whether the object can undo changes (TRUE) or not (FALSE). + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// E_UNEXPECTED + /// An unexpected error has occurred. + /// + /// + /// + /// + /// + /// The object indicates whether it can undo changes through the fUndoable flag. If the object can undo changes, the container + /// can (by the user invoking the Edit Undo command) call the IOleInPlaceObject::ReactivateAndUndo method to undo the changes. + /// + /// Notes to Callers + /// + /// IOleInPlaceSite::OnUIDeactivate is called by the site's immediate child object when it is deactivating to notify the + /// container that it should reinstall its own user interface components and take focus. The container should wait for the call + /// to IOleInPlaceSite::OnUIDeactivate to complete before fully cleaning up and destroying any composite submenus. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplacesite-onuideactivate HRESULT OnUIDeactivate( + // BOOL fUndoable ); + [PreserveSig] + HRESULT OnUIDeactivate([MarshalAs(UnmanagedType.Bool)] bool fUndoable); + + /// Notifies the container that the object is no longer active in place. + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// E_UNEXPECTED + /// An unexpected error has occurred. + /// + /// + /// + /// + /// Notes to Callers + /// + /// OnInPlaceDeactivate is called by an in-place object when it is fully deactivated. This function notifies the + /// container that the object has been deactivated, and it gives the container a chance to run code pertinent to the object's + /// deactivation. In particular, OnInPlaceDeactivate is called as a result of IOleInPlaceObject::InPlaceDeactivate being + /// called. Calling OnInPlaceDeactivate indicates that the object can no longer support Undo. + /// + /// Notes to Implementers + /// + /// If the container is holding pointers to the IOleInPlaceObject and IOleInPlaceActiveObject interface implementations, it + /// should release them after the OnInPlaceDeactivate call. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplacesite-oninplacedeactivate HRESULT OnInPlaceDeactivate(); + [PreserveSig] + HRESULT OnInPlaceDeactivate(); + + /// Instructs the container to discard its undo state. The container should not call IOleInPlaceObject::ReActivateAndUndo. + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// E_UNEXPECTED + /// An unexpected error has occurred. + /// + /// + /// + /// + /// + /// If an object is activated in place and the object's associated object application maintains only one level of undo, there is + /// no need to have more than one entry on the undo stack. That is, after a change has been made to the active object that + /// invalidates its undo state saved by the container, there is no need to maintain this undo state in the container. + /// + /// Notes to Callers + /// + /// DiscardUndoState is called by the active object while performing some action that would discard the undo state of the + /// object. The in-place object calls this method to notify the container to discard the object's last saved undo state. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplacesite-discardundostate HRESULT DiscardUndoState(); + [PreserveSig] + HRESULT DiscardUndoState(); + + /// Deactivates the object, ends the in-place session, and reverts to the container's saved undo state. + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// E_UNEXPECTED + /// An unexpected error has occurred. + /// + /// + /// + /// + /// Notes to Callers + /// Called by the active object when the user invokes undo just after activating the object. + /// Notes to Implementers + /// + /// Upon completion of this call, the container should call IOleInPlaceObject::UIDeactivate to remove the user interface for the + /// object, activate itself, and undo. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplacesite-deactivateandundo HRESULT DeactivateAndUndo(); + [PreserveSig] + HRESULT DeactivateAndUndo(); + + /// Notifies the container that the object extents have changed. + /// + /// A pointer a RECT structure that contains the position of the in-place object in the client coordinates of its parent window. + /// + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// E_INVALIDARG + /// The supplied pointer is invalid. + /// + /// + /// E_UNEXPECTED + /// An unexpected error occurred. + /// + /// + /// + /// + /// Notes to Callers + /// The OnPosRectChange method is called by the in-place object. + /// Notes to Implementers + /// + /// When the in-place object calls OnPosRectChange, the container must call IOleInPlaceObject::SetObjectRects to specify + /// the new position of the in-place window and the clipping rectangle. Only then does the object resize its window. + /// + /// + /// In most cases, the object grows to the right and/or down. There could be cases where the object grows to the left and/or up, + /// as conveyed through lprcPosRect. It is also possible to change the object's position without changing its size. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplacesite-onposrectchange HRESULT OnPosRectChange( + // LPCRECT lprcPosRect ); + [PreserveSig] + HRESULT OnPosRectChange(in RECT lprcPosRect); + } + + /// + /// Implemented by container applications and used by object applications to negotiate border space on the document or frame window. + /// The container provides a RECT structure in which the object can place toolbars and other similar controls, determines if tools + /// can in fact be installed around the object's window frame, allocates space for the border, and establishes a communication + /// channel between the object and each frame and document window. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nn-oleidl-ioleinplaceuiwindow + [PInvokeData("oleidl.h", MSDNShortId = "3cfb31aa-9746-438c-af64-8236c170fe88")] + [ComImport, Guid("00000115-0000-0000-C000-000000000046"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IOleInPlaceUIWindow : IOleWindow + { + /// + /// Retrieves a handle to one of the windows participating in in-place activation (frame, document, parent, or in-place object window). + /// + /// A pointer to a variable that receives the window handle. + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// E_FAIL + /// The object is windowless. + /// + /// + /// E_OUTOFMEMORY + /// There is insufficient memory available for this operation. + /// + /// + /// E_UNEXPECTED + /// An unexpected error has occurred. + /// + /// + /// + /// + /// + /// Five types of windows comprise the windows hierarchy. When a object is active in place, it has access to some or all of + /// these windows. + /// + /// + /// + /// Window + /// Description + /// + /// + /// Frame + /// The outermost main window where the container application's main menu resides. + /// + /// + /// Document + /// The window that displays the compound document containing the embedded object to the user. + /// + /// + /// Pane + /// + /// The subwindow of the document window that contains the object's view. Applicable only for applications with split-pane windows. + /// + /// + /// + /// Parent + /// + /// The container window that contains that object's view. The object application installs its window as a child of this window. + /// + /// + /// + /// In-place + /// + /// The window containing the active in-place object. The object application creates this window and installs it as a child of + /// its hatch window, which is a child of the container's parent window. + /// + /// + /// + /// + /// Each type of window has a different role in the in-place activation architecture. However, it is not necessary to employ a + /// separate physical window for each type. Many container applications use the same window for their frame, document, pane, and + /// parent windows. + /// + /// + [PreserveSig] + new HRESULT GetWindow(out HWND phwnd); + + /// Determines whether context-sensitive help mode should be entered during an in-place activation session. + /// + /// if help mode should be entered; if it should be exited. + /// + /// + /// + /// This method returns S_OK if the help mode was entered or exited successfully, depending on the value passed in . Other possible return values include the following.
+ /// + /// + /// + /// Return code + /// Description + /// + /// + /// E_INVALIDARG + /// The specified value is not valid. + /// + /// + /// E_OUTOFMEMORY + /// There is insufficient memory available for this operation. + /// + /// + /// E_UNEXPECTED + /// An unexpected error has occurred. + /// + /// + /// + /// + /// Applications can invoke context-sensitive help when the user: + /// + /// presses SHIFT+F1, then clicks a topic + /// presses F1 when a menu item is selected + /// + /// + /// When SHIFT+F1 is pressed, either the frame or active object can receive the keystrokes. If the container's frame receives + /// the keystrokes, it calls its containing document's IOleWindow::ContextSensitiveHelp method with set to . This propagates the help state to all of its in-place objects so they can + /// correctly handle the mouse click or WM_COMMAND. + /// + /// + /// If an active object receives the SHIFT+F1 keystrokes, it calls the container's IOleWindow::ContextSensitiveHelp method with + /// set to , which then recursively calls each of its in-place sites until + /// there are no more to be notified. The container then calls its document's or frame's IOleWindow::ContextSensitiveHelp method + /// with set to . + /// + /// When in context-sensitive help mode, an object that receives the mouse click can either: + /// + /// Ignore the click if it does not support context-sensitive help. + /// + /// Tell all the other objects to exit context-sensitive help mode with ContextSensitiveHelp set to FALSE and then provide help + /// for that context. + /// + /// + /// + /// An object in context-sensitive help mode that receives a WM_COMMAND should tell all the other in-place objects to exit + /// context-sensitive help mode and then provide help for the command. + /// + /// + /// If a container application is to support context-sensitive help on menu items, it must either provide its own message filter + /// so that it can intercept the F1 key or ask the OLE library to add a message filter by calling OleSetMenuDescriptor, passing + /// valid, non-NULL values for the lpFrame and lpActiveObj parameters. + /// + /// + [PreserveSig] + new HRESULT ContextSensitiveHelp([MarshalAs(UnmanagedType.Bool)] bool fEnterMode); + + /// Retrieves the outer rectange for toolbars and controls while the object is active in place. + /// + /// A pointer to a RECT structure where the outer rectangle is to be returned. The structure's coordinates are relative to the + /// window being represented by the interface. + /// + /// + /// Notes to Callers + /// + /// The IOleInPlaceUIWindow::GetBorder function, when called on a document or frame window object, returns the outer + /// rectangle (relative to the window) where the object can put toolbars or similar controls. + /// + /// + /// If the object is to install these tools, it should negotiate space for the tools within this rectangle using + /// IOleInPlaceUIWindow::RequestBorderSpace and then call IOleInPlaceUIWindow::SetBorderSpace to get this space allocated. + /// + /// + /// Note While executing IOleInPlaceUIWindow::GetBorder, do not make calls to the PeekMessage or GetMessage + /// functions, or a dialog box. Doing so may cause the system to deadlock. There are further restrictions on which OLE interface + /// methods and functions can be called from within GetBorder. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplaceuiwindow-getborder HRESULT GetBorder( LPRECT + // lprectBorder ); + void GetBorder(out RECT lprectBorder); + + /// + /// Determines whether there is space available for tools to be installed around the object's window frame while the object is + /// active in place. + /// + /// + /// A pointer to a BORDERWIDTHS structure containing the requested widths (in pixels) needed on each side of the window for the tools. + /// + /// + /// Notes to Callers + /// + /// The active in-place object calls IOleInPlaceUIWindow::RequestBorderSpace to ask if tools can be installed inside the + /// window frame. These tools would be allocated between the rectangle returned by IOleInPlaceUIWindow::GetBorder and the + /// BORDERWIDTHS structure specified in the argument to this call. + /// + /// + /// The space for the tools is not actually allocated to the object until it calls IOleInPlaceUIWindow::SetBorderSpace, allowing + /// the object to negotiate for space (such as while dragging toolbars around), but deferring the moving of tools until the + /// action is completed. + /// + /// + /// The object can install these tools by passing the width in pixels that is to be used on each side. For example, if the + /// object required 10 pixels on the top, 0 pixels on the bottom, and 5 pixels on the left and right sides, it would pass the + /// following BORDERWIDTHS structure to IOleInPlaceUIWindow::RequestBorderSpace: + /// + /// + /// Note While executing IOleInPlaceUIWindow::RequestBorderSpace, do not make calls to the PeekMessage or + /// GetMessage functions, or a dialog box. Doing so may cause the system to deadlock. There are further restrictions on which + /// OLE interface methods and functions can be called from within IOleInPlaceUIWindow::RequestBorderSpace. + /// + /// Notes to Implementers + /// + /// If the amount of space an active object uses for its toolbars is irrelevant to the container, it can simply return NOERROR + /// as shown in the following IOleInPlaceUIWindow::RequestBorderSpace example. Containers should not unduly restrict the + /// display of tools by an active in-place object. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplaceuiwindow-requestborderspace HRESULT + // RequestBorderSpace( LPCBORDERWIDTHS pborderwidths ); + void RequestBorderSpace(in RECT pborderwidths); + + /// Allocates space for the border requested in the call to IOleInPlaceUIWindow::RequestBorderSpace. + /// + /// Pointer to a BORDERWIDTHS structure containing the requested width of the tools, in pixels. It can be NULL, + /// indicating the object does not need any space. + /// + /// + /// The object must call IOleInPlaceUIWindow::SetBorderSpace. It can do any one of the following: + /// + /// + /// Use its own toolbars, requesting border space of a specific size. + /// + /// + /// + /// Use no toolbars, but force the container to remove its toolbars by passing a valid BORDERWIDTHS structure containing nothing + /// but zeros in the pborderwidths parameter. + /// + /// + /// + /// + /// Use no toolbars but allow the in-place container to leave its toolbars up by passing NULL as the pborderwidths parameter. + /// + /// + /// + /// + /// The BORDERWIDTHS structure used in this call would generally have been passed in a previous call to + /// IOleInPlaceUIWindow::RequestBorderSpace, which must have returned S_OK. + /// + /// + /// If an object must renegotiate space on the border, it can call IOleInPlaceUIWindow::SetBorderSpace again with the new + /// widths. If the call to IOleInPlaceUIWindow::SetBorderSpace fails, the object can do a full negotiation for border + /// space with calls to IOleInPlaceUIWindow::GetBorder, IOleInPlaceUIWindow::RequestBorderSpace, and IOleInPlaceUIWindow::SetBorderSpace. + /// + /// + /// Note While executing IOleInPlaceUIWindow::SetBorderSpace, do not make calls to the PeekMessage or GetMessage + /// functions, or a dialog box. Doing so may cause the system to deadlock. There are further restrictions on which OLE interface + /// methods and functions can be called from within IOleInPlaceUIWindow::SetBorderSpace. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplaceuiwindow-setborderspace HRESULT + // SetBorderSpace( LPCBORDERWIDTHS pborderwidths ); + void SetBorderSpace(in RECT pborderwidths); + + /// Provides a direct channel of communication between the object and each of the frame and document windows. + /// A pointer to the IOleInPlaceActiveObject interface on the active in-place object. + /// + /// A pointer to a string containing a name that describes the object an embedding container can use in composing its window + /// title. It can be NULL if the object does not require the container to change its window titles. Containers should + /// ignore this parameter and always use their own name in the title bar. + /// + /// + /// + /// Generally, an embedded object should pass NULL for the pszObjName parameter (see Notes to Implementers below). + /// However, if you are working in conjunction with a container that does display the name of the in-place active object in its + /// title bar, then you should compose a string in the following form: <application name> – <object short-type name>. + /// + /// Notes to Callers + /// + /// IOleInPlaceUIWindow::SetActiveObject is called by the object to establish a direct communication link between itself + /// and the document and frame windows. + /// + /// + /// When deactivating, the object calls IOleInPlaceUIWindow::SetActiveObject, passing NULL for the pActiveObject + /// and pszObjName parameters. + /// + /// + /// An object must call IOleInPlaceUIWindow::SetActiveObject before calling IOleInPlaceFrame::SetMenu to give the + /// container the pointer to the active object. The container then uses this pointer in processing + /// IOleInPlaceFrame::SetMenu and to pass to OleSetMenuDescriptor. + /// + /// Notes to Implementers + /// + /// The Microsoft Windows User Interface Design Guide recommends that an in-place container ignore the pszObjName parameter + /// passed in this method. The guide says "The title bar is not affected by in-place activation. It always displays the + /// top-level container's name." + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleinplaceuiwindow-setactiveobject HRESULT + // SetActiveObject( IOleInPlaceActiveObject *pActiveObject, LPCOLESTR pszObjName ); + void SetActiveObject([In] IOleInPlaceActiveObject pActiveObject, [MarshalAs(UnmanagedType.LPWStr)] string pszObjName); + } + + /// + /// + /// Enables a linked object to provide its container with functions pertaining to linking. The most important of these functions is + /// binding to the link source, that is, activating the connection to the document that stores the linked object's native data. + /// IOleLink also defines functions for managing information about the linked object, such as the location of the link source + /// and the cached presentation data for the linked object. + /// + /// + /// A container application can distinguish between embedded objects and linked objects by querying for IOleLink; only linked + /// objects implement IOleLink. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nn-oleidl-iolelink + [PInvokeData("oleidl.h", MSDNShortId = "NN:oleidl.IOleLink")] + [ComImport, Guid("0000011d-0000-0000-C000-000000000046"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IOleLink + { + /// Specifies how often a linked object should update its cached data. + /// + /// Specifies how often a linked object should update its cached data. The possible values for dwUpdateOpt are taken from + /// the enumeration OLEUPDATE. + /// + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// E_INVALIDARG + /// The supplied value is invalid. + /// + /// + /// + /// + /// Notes to Callers + /// + /// Your container application should call IOleLink::SetUpdateOptions when the end user changes the update option for a + /// linked object. + /// + /// + /// The end user selects the update option for a linked object using the Links dialog box. If you use the OleUIEditLinks + /// function to display this dialog box, you must implement the IOleUILinkContainer interface. The dialog box calls your + /// IOleUILinkContainer::SetLinkUpdateOptions method to specify the update option chosen by the end user. Your implementation of + /// this method should call the IOleLink::SetUpdateOptions method to pass the selected option to the linked object. + /// + /// Notes to Implementers + /// + /// The default update option is OLEUDPATE_ALWAYS. The linked object's implementation of IPersistStorage::Save saves the current + /// update option. + /// + /// + /// If OLEUDPATE_ALWAYS is specified as the update option, the linked object updates the link's caches in the following situations: + /// + /// + /// + /// When the update option is changed from manual to automatic, if the link source is running. + /// + /// + /// Whenever the linked object binds to the link source. + /// + /// + /// + /// Whenever the link source is running and the linked object's IOleObject::Close, IPersistStorage::Save, or IAdviseSink::OnSave + /// implementations are called. + /// + /// + /// + /// + /// For both manual and automatic links, the linked object updates the cache whenever the container application calls + /// IOleObject::Update or IOleLink::Update. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolelink-setupdateoptions HRESULT SetUpdateOptions( [in] + // DWORD dwUpdateOpt ); + [PreserveSig] + HRESULT SetUpdateOptions(OLEUPDATE dwUpdateOpt); + + /// Retrieves a value indicating how often the linked object updates its cached data. + /// + /// A pointer to a variable that receives the current value for the linked object's update option, indicating how often the + /// linked object updates the cached data for the linked object. The possible values for pdwUpdateOpt are taken from the + /// enumeration OLEUPDATE. + /// + /// This method returns S_OK on success. + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolelink-getupdateoptions HRESULT GetUpdateOptions( [out] + // DWORD *pdwUpdateOpt ); + [PreserveSig] + HRESULT GetUpdateOptions(out OLEUPDATE pdwUpdateOpt); + + /// Sets the moniker for the link source. + /// + /// A pointer to the IMoniker interface on a moniker that identifies the new link source of the linked object. A value of + /// NULL breaks the link. + /// + /// + /// The CLSID of the link source that the linked object should use to access information about the linked object when it is not bound. + /// + /// This method returns S_OK on success. + /// + /// Notes to Callers + /// + /// Your container application can call IOleLink::SetSourceMoniker when the end user changes the source of a link or + /// breaks a link. Note that this requires your container to use the MkParseDisplayName function to create a moniker out of the + /// display name that the end user enters. If you'd rather have the linked object perform the parsing, your container can call + /// IOleLink::SetSourceDisplayName instead of IOleLink::SetSourceMoniker. + /// + /// + /// The end user changes the source of a link or breaks a link using the Links dialog box. If you use the OleUIEditLinks + /// function to display the Links dialog box, you must implement the IOleUILinkContainer interface. The dialog box calls + /// your implementations of IOleUILinkContainer::SetLinkSource and IOleUILinkContainer::CancelLink; your implementation of these + /// methods can call IOleLink::SetSourceMoniker. + /// + /// + /// If the linked object is currently bound to its link source, the linked object's implementation of + /// IOleLink::SetSourceMoniker closes the link before changing the moniker. + /// + /// Notes to Implementers + /// + /// The IOleLink contract does not specify how the linked object stores or uses the link source moniker. The provided + /// implementation stores the absolute moniker specified when the link is created or when the moniker is changed; it then + /// computes and stores a relative moniker. Future implementations might manage monikers differently to provide better moniker + /// tracking. The absolute moniker provides the complete path to the link source. The linked object uses this absolute moniker + /// and the moniker of the compound document to compute a relative moniker that identifies the link source relative to the + /// compound document that contains the link. + /// + /// pmkCompoundDoc->RelativePathTo(pmkAbsolute, ppmkRelative) + /// + /// When binding to the link source, the linked object first tries to bind using the relative moniker. If that fails, it tries to + /// bind the absolute moniker. + /// + /// + /// When the linked object successfully binds using either the relative or the absolute moniker, it automatically updates the + /// other moniker. The linked object also updates both monikers when it is bound to the link source and it receives a rename + /// notification through the IAdviseSink::OnRename method. A container application can also use the + /// IOleLink::SetSourceDisplayName method to change a link's moniker. + /// + /// The linked object's implementation of IPersistStorage::Save saves both the relative and the absolute moniker. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolelink-setsourcemoniker HRESULT SetSourceMoniker( [in] + // IMoniker *pmk, [in] REFCLSID rclsid ); + [PreserveSig] + HRESULT SetSourceMoniker([In, Optional] IMoniker pmk, in Guid rclsid); + + /// Retrieves the moniker identifying the link source of a linked object. + /// + /// Address of an IMoniker pointer variable that receives the interface pointer to an absolute moniker that identifies the link + /// source. When successful, the implementation must call AddRef on ppmk; it is the caller's responsibility to call + /// Release. If an error occurs the implementation must set ppmk to NULL. + /// + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// MK_E_UNAVAILABLE + /// No moniker is available. + /// + /// + /// + /// + /// Notes to Callers + /// + /// Your container application can call IOleLink::GetSourceMoniker to display the current source of a link in the + /// Links dialog box. Note that this requires your container to use the IMoniker::GetDisplayName method to get the display + /// name of the moniker. If you would rather get the display name directly, your container can call + /// IOleLink::GetSourceDisplayName instead of IOleLink::GetSourceMoniker. + /// + /// + /// If you use the OleUIEditLinks function to display the Links dialog box, you must implement the IOleUILinkContainer + /// interface. The dialog box calls your implementations of IOleUILinkContainer::GetLinkSource to get the string it should + /// display. Your implementation of that method can call IOleLink::GetSourceMoniker. + /// + /// Notes to Implementers + /// + /// The linked object stores both an absolute and a relative moniker for the link source. If the relative moniker is non- + /// NULL and a moniker is available for the compound document, IOleLink::GetSourceMoniker returns the moniker + /// created by composing the relative moniker onto the end of the compound document's moniker. Otherwise, it returns the absolute + /// moniker or, if an error occurs, NULL. + /// + /// + /// The container specifies the absolute moniker when it calls one of the OleCreateLink functions to create a link. The + /// application can call IOleLink::GetSourceMoniker or IOleLink::GetSourceDisplayName to change the absolute moniker. In + /// addition, the linked object automatically updates the monikers whenever it successfully binds to the link source, or when it + /// is bound to the link source and it receives a rename notification through the IAdviseSink::OnRename method. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolelink-getsourcemoniker HRESULT GetSourceMoniker( [out] + // IMoniker **ppmk ); + [PreserveSig] + HRESULT GetSourceMoniker(out IMoniker ppmk); + + /// Sets the display name for the link source. + /// A pointer to the display name of the new link source. This parameter cannot be NULL. + /// + /// This method returns S_OK on success. + /// Values from MkParseDisplayName may also be returned here. + /// + /// + /// Notes to Callers + /// + /// Your container application can call IOleLink::SetSourceDisplayName when the end user changes the source of a link or + /// breaks a link. Note that this requires the linked object to create a moniker out of the display name. If you'd rather parse + /// the display name into a moniker yourself, your container can call IOleLink::SetSourceMoniker instead of IOleLink::SetSourceDisplayName. + /// + /// + /// If you use the OleUIEditLinks function to display the Links dialog box, you must implement the IOleUILinkContainer + /// interface. The dialog box calls your implementations of IOleUILinkContainer::SetLinkSource and + /// IOleUILinkContainer::CancelLink. Your implementation of these methods can call IOleLink::SetSourceDisplayName. + /// + /// + /// If your container application is immediately going to bind to a newly specified link source, you should call + /// MkParseDisplayName and IOleLink::SetSourceMoniker instead, and then call IOleLink::BindToSource using the bind context from + /// the parsing operation. By reusing the bind context, you can avoid redundant loading of objects that might otherwise occur. + /// + /// Notes to Implementers + /// + /// The contract for IOleLink::SetSourceDisplayName does not specify when the linked object will parse the display name + /// into a moniker. The parsing can occur before IOleLink::SetSourceDisplayName returns, or the linked object can store + /// the display name and parse it only when it needs to bind to the link source. Note that parsing the display name is + /// potentially an expensive operation because it might require binding to the link source. The provided implementation of + /// IOleLink::SetSourceDisplayName parses the display name and then releases the bind context used in the parse operation. + /// This can result in running and then stopping the link source server. + /// + /// + /// If the linked object is bound to the current link source, the implementation of IOleLink::SetSourceDisplayName breaks + /// the connection. + /// + /// For more information on how the linked object stores and uses the moniker to the link source, see IOleLink::SetSourceMoniker. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolelink-setsourcedisplayname HRESULT + // SetSourceDisplayName( [in] LPCOLESTR pszStatusText ); + [PreserveSig] + HRESULT SetSourceDisplayName([MarshalAs(UnmanagedType.LPWStr)] string pszStatusText); + + /// Retrieves the display name of the link source of the linked object. + /// + /// Address of a pointer variable that receives a pointer to the display name of the link source. If an error occurs, + /// ppszDisplayName is set to NULL; otherwise, the implementation must use IMalloc::Alloc to allocate the string + /// returned in ppszDisplayName, and the caller is responsible for calling IMalloc::Free to free it. Both caller and + /// called use the allocator returned by CoGetMalloc. + /// + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// E_FAIL + /// The operation failed. + /// + /// + /// + /// Retrieving the display name requires calling these functions; therefore, this method may return errors generated by + /// CreateBindCtx and IMoniker::GetDisplayName. + /// + /// + /// + /// Notes to Callers + /// Your container application can call IOleLink::GetSourceDisplayName to display the current source of a link. + /// + /// The current source of a link is displayed in the Links dialog box. If you use the OleUIEditLinks function to display + /// the Links dialog box, you must implement the IOleUILinkContainer interface. The dialog box calls your implementations + /// of IOleUILinkContainer::GetLinkSource to get the string it should display. Your implementation of that method can call IOleLink::GetSourceDisplayName. + /// + /// Notes to Implementers + /// + /// The linked object's implementation of IOleLink::GetSourceDisplayName calls IOleLink::GetSourceMoniker to get the link + /// source moniker, and then calls IMoniker::GetDisplayName to get that moniker's display name. This operation is potentially + /// expensive because it might require binding the moniker. All of the system-provided monikers can return a display name without + /// binding, but there is no guarantee that other moniker implementations can. Instead of making repeated calls to + /// IOleLink::GetSourceDisplayName, your container application can cache the name and update it whenever the link source + /// is bound. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolelink-getsourcedisplayname HRESULT + // GetSourceDisplayName( [out] LPOLESTR *ppszDisplayName ); + [PreserveSig] + HRESULT GetSourceDisplayName(out IntPtr ppszDisplayName); + + /// Activates the connection to the link source by binding the moniker stored within the linked object. + /// + /// Specifies how to proceed if the link source has a different CLSID from the last time it was bound. If this parameter is zero + /// and the CLSIDs are different, the method fails and returns OLE_E_CLASSDIFF. If the OLELINKBIND_EVENIFCLASSDIFF value from the + /// OLELINKBIND enumeration is specified and the CLSIDs are different, the method binds successfully and updates the CLSID stored + /// in the linked object. + /// + /// + /// A pointer to the IBindCtx interface on the bind context to be used in this binding operation. This parameter can be + /// NULL. The bind context caches objects bound during the binding process, contains parameters that apply to all + /// operations using the bind context, and provides the means by which the binding implementation should retrieve information + /// about its environment. For more information, see IBindCtx. + /// + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// OLE_E_CLASSDIFF + /// + /// The link source was not bound because its CLSID has changed. This error is returned only if the OLELINKBIND_EVENIFCLASSDIFF + /// flag is not specified in the bindflags parameter. + /// + /// + /// + /// MK_E_NOOBJECT + /// + /// The link source could not be found or (if the link source's moniker is a composite) some intermediate object identified in + /// the composite could not be found. + /// + /// + /// + /// E_UNSPEC + /// The link's moniker is NULL. + /// + /// + /// + /// Binding the moniker might require calling the CreateBindCtx function; therefore, this method may return errors generated by CreateBindCtx. + /// + /// + /// + /// Notes to Callers + /// + /// Typically, your container application does not need to call the IOleLink::BindToSource method directly. When it's + /// necessary to activate the connection to the link source, your container typically calls IOleObject::DoVerb, + /// IOleObject::Update, or IOleLink::Update. The linked object's implementation of these methods calls + /// IOleLink::BindToSource. Your container can also call the OleRun function, which calls IOleLink::BindToSource + /// when called on a linked object. + /// + /// + /// In each of the examples listed previously, in which IOleLink::BindToSource is called indirectly, the bindflags + /// parameter is set to zero. Consequently, these calls can fail with the OLE_E_CLASSDIFF error if the class of the link source + /// is different from what it was the last time the linked object was bound. This could happen, for example, if the original link + /// source was an embedded Lotus spreadsheet that an end user had subsequently converted (using the Change Type dialog box) to an + /// Excel spreadsheet. + /// + /// + /// If you want your container to bind even though the link source now has a different CLSID, you can call + /// IOleLink::BindToSource directly and specify OLELINKBIND_EVENIFCLASSDIFF for the bindflags parameter. This call binds + /// to the link source and updates the link object's CLSID. Alternatively, your container can delete the existing link and use + /// the OleCreateLink function to create a new linked object. + /// + /// Notes to Implementers + /// The linked object caches the interface pointer to the link source acquired during binding. + /// + /// The linked object's IOleLink::BindToSource implementation first tries to bind using a moniker consisting of the + /// compound document's moniker composed with the link source's relative moniker. If successful, it updates the link's absolute + /// moniker. Otherwise, it tries to bind using the absolute moniker, updating the relative moniker if successful. + /// + /// + /// If IOleLink::BindToSource binds to the link source, it calls the compound document's IOleContainer::LockContainer + /// implementation to keep the containing compound document alive while the link source is running. IOleLink::BindToSource + /// also calls the IOleObject::Advise and IDataObject::DAdvise implementations of the link source to set up advisory connections. + /// The IOleLink::UnbindSource implementation unlocks the container and deletes the advisory connections. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolelink-bindtosource HRESULT BindToSource( [in] DWORD + // bindflags, [in] IBindCtx *pbc ); + [PreserveSig] + HRESULT BindToSource(OLELINKBIND bindflags, [In, Optional] IBindCtx pbc); + + /// Activates the connection between the linked object and the link source if the link source is already running. + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// S_FALSE + /// The link source is not running. + /// + /// + /// + /// Binding the moniker might require calling CreateBindCtx, IMoniker::IsRunning, or IOleLink::BindToSource; therefore, errors + /// generated by these functions can also be returned. + /// + /// + /// + /// You typically do not need to call IOleLink::BindIfRunning. This method is primarily called by the linked object. + /// Notes to Implementers + /// + /// The linked object's implementation of IOleLink::BindIfRunning checks the running object table (ROT) to determine + /// whether the link source is already running. It checks both the relative and absolute monikers. If the link source is running, + /// IOleLink::BindIfRunning calls IOleLink::BindToSource to connect the linked object to the link source. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolelink-bindifrunning HRESULT BindIfRunning(); + [PreserveSig] + HRESULT BindIfRunning(); + + /// Retrieves a pointer to the link source if the connection is active. + /// + /// Address of IDataObject pointer variable that receives the interface pointer to the link source. When successful, the + /// implementation must call IUnknown::AddRef on ppunk; it is the caller's responsibility to call IUnknown::Release. If an + /// error occurs, the implementation sets ppunk to NULL. + /// + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// E_FAIL + /// The operation failed. + /// + /// + /// + /// You typically do not need to call IOleLink::GetBoundSource. + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolelink-getboundsource HRESULT GetBoundSource( [out] + // IUnknown **ppunk ); + [PreserveSig] + HRESULT GetBoundSource(out IDataObject ppunk); + + /// Breaks the connection between a linked object and its link source. + /// This method returns S_OK on success. + /// + /// + /// You typically do not call UnbindSource directly. When it's necessary to deactivate the connection to the link source, + /// your container typically calls IOleObject::Close or IUnknown::Release; the linked object's implementation of these methods + /// calls UnbindSource. The linked object's IAdviseSink::OnClose implementation also calls UnbindSource. + /// + /// Notes to Implementers + /// + /// The linked object's implementation of UnbindSource does nothing if the link source is not currently bound. If the link + /// source is bound, UnbindSource calls the link source's IOleObject::Unadvise and IDataObject::DUnadvise implementations + /// to delete the advisory connections to the link source. The UnbindSource method also calls the compound document's + /// IOleContainer::LockContainer implementation to unlock the containing compound document. This undoes the lock on the container + /// and the advisory connections that were established in IOleLink::BindToSource. UnbindSource releases all the linked + /// object's interface pointers to the link source. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolelink-unbindsource HRESULT UnbindSource(); + [PreserveSig] + HRESULT UnbindSource(); + + /// + /// Updates the compound document's cached data for a linked object. This involves binding to the link source, if it is not + /// already bound. + /// + /// + /// A pointer to the IBindCtx interface on the bind context to be used in binding the link source. This parameter can be + /// NULL. The bind context caches objects bound during the binding process, contains parameters that apply to all + /// operations using the bind context, and provides the means by which the binding implementation should retrieve information + /// about its environment. For more information, see IBindCtx. + /// + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// CACHE_E_NOCACHE_UPDATE + /// The bind operation worked but no caches were updated. + /// + /// + /// CACHE_S_SOMECACHES_NOTUPDATED + /// The bind operation worked but not all caches were updated. + /// + /// + /// OLE_E_CANT_BINDTOSOURCE + /// Unable to bind to the link source. + /// + /// + /// + /// + /// Notes to Callers + /// Your container application should call Update if the end user updates the cached data for a linked object. + /// + /// The end user can update the cached data for a linked object by choosing the Update Now button in the Links + /// dialog box. If you use the OleUIEditLinks function to display the Links dialog box, you must implement the + /// IOleUILinkContainer interface. The dialog box calls your implementations of IOleUILinkContainer::UpdateLink when the end user + /// chooses the Update Now button. Your implementation of that method can call Update. + /// + /// + /// Your container application can also call Update to update a linked object, because that method calls Update + /// when it is called on a linked object. + /// + /// + /// This method updates both automatic links and manual links. For manual links, calling Update or Update is the + /// only way to update the caches. For more information on automatic and manual links, see IOleLink::SetUpdateOptions. + /// + /// Notes on Implementation + /// + /// If pbc is non- NULL, the linked object's implementation of Update calls IBindCtx::RegisterObjectBound to + /// register the bound link source. This ensures that the link source remains running until the bind context is released. + /// + /// The current caches are left intact if the link source cannot be bound. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iolelink-update HRESULT Update( [in] IBindCtx *pbc ); + [PreserveSig] + HRESULT Update([In, Optional] IBindCtx pbc); + } + + /// + /// Serves as the principal means by which an embedded object provides basic functionality to, and communicates with, its container. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nn-oleidl-ioleobject + [PInvokeData("oleidl.h", MSDNShortId = "58b32c87-39b6-4d64-9174-cf798ed302c2")] + [ComImport, Guid("00000112-0000-0000-C000-000000000046"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IOleObject + { + /// Informs an embedded object of its display location, called a "client site," within its container. + /// Pointer to the IOleClientSite interface on the container application's client-site. + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// E_UNEXPECTED + /// An unexpected error occurred. + /// + /// + /// + /// + /// + /// Within a compound document, each embedded object has its own client site — the place where it is displayed and through + /// which it receives information about its storage, user interface, and other resources. IOleObject::SetClientSite is + /// the only method enabling an embedded object to obtain a pointer to its client site. + /// + /// Notes to Callers + /// + /// A container can notify an object of its client site either at the time the object is created or, subsequently, when the + /// object is initialized. + /// + /// + /// When creating or loading an object, a container may pass a client-site pointer (along with other arguments) to one of the + /// following helper functions: OleCreate, OleCreateFromFile, OleCreateFromData or OleLoad. These helper functions load an + /// object handler for the new object and call IOleObject::SetClientSite on the container's behalf before returning a + /// pointer to the new object. + /// + /// + /// Passing a client-site pointer informs the object handler that the client site is ready to process requests. If the client + /// site is unlikely to be ready immediately after the handler is loaded, you may want your container to pass a NULL + /// client-site pointer to the helper function. The NULL pointer says that no client site is available and thereby defers + /// notifying the object handler of the client site until the object is initialized. In response, the helper function returns a + /// pointer to the object, but upon receiving that pointer the container must call IOleObject::SetClientSite as part of + /// initializing the new object. + /// + /// Notes to Implementers + /// Implementation consists simply of incrementing the reference count on, and storing, the pointer to the client site. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleobject-setclientsite HRESULT SetClientSite( + // IOleClientSite *pClientSite ); + [PreserveSig] + HRESULT SetClientSite(IOleClientSite pClientSite); + + /// Retrieves a pointer to an embedded object's client site. + /// + /// Address of IOleClientSite pointer variable that receives the interface pointer to the object's client site. If an object + /// does not yet know its client site, or if an error has occurred, ppClientSite must be set to NULL. Each time an object + /// receives a call to IOleObject::GetClientSite, it must increase the reference count on ppClientSite. It is the + /// caller's responsibility to call Release when it is done with ppClientSite. + /// + /// This method returns S_OK on success. + /// + /// + /// Link clients most commonly call the IOleObject::GetClientSite method in conjunction with the + /// IOleClientSite::GetContainer method to traverse a hierarchy of nested objects. A link client calls + /// IOleObject::GetClientSite to get a pointer to the link source's client site. The client then calls + /// IOleClientSite::GetContainer to get a pointer to the link source's container. Finally, the client calls + /// QueryInterface to get IOleObject and IOleObject::GetClientSite to get the container's client site within its + /// container. By repeating this sequence of calls, the caller can eventually retrieve a pointer to the master container in + /// which all the other objects are nested. + /// + /// Notes to Callers + /// + /// The returned client-site pointer will be NULL if an embedded object has not yet been informed of its client site. + /// This will be the case with a newly loaded or created object when a container has passed a NULL client-site pointer to + /// one of the object-creation helper functions but has not yet called IOleObject::SetClientSite as part of initializing the object. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleobject-getclientsite HRESULT GetClientSite( + // IOleClientSite **ppClientSite ); + [PreserveSig] + HRESULT GetClientSite(out IOleClientSite ppClientSite); + + /// Provides an object with the names of its container application and the compound document in which it is embedded. + /// Pointer to the name of the container application in which the object is running. + /// + /// Pointer to the name of the compound document that contains the object. If you do not wish to display the name of the + /// compound document, you can set this parameter to NULL. + /// + /// This method returns S_OK on success. + /// + /// Notes for Callers + /// + /// Call IOleObject::SetHostNames only for embedded objects, because for linked objects, the link source provides its own + /// separate editing window and title bar information. + /// + /// Notes to Implementers + /// + /// An object's application of IOleObject::SetHostNames should include whatever modifications to its user interface may + /// be appropriate to an object's embedded state. Such modifications typically will include adding and removing menu commands + /// and altering the text displayed in the title bar of the editing window. + /// + /// + /// The complete window title for an embedded object in an SDI container application or an MDI application with a maximized + /// child window should appear as follows: + /// + /// Otherwise, the title should be: + /// + /// The "object short type" refers to a form of an object's name short enough to be displayed in full in a list box. Because + /// these identifying strings are not stored as part of the persistent state of the object, IOleObject::SetHostNames must + /// be called each time the object loads or runs. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleobject-sethostnames HRESULT SetHostNames( LPCOLESTR + // szContainerApp, LPCOLESTR szContainerObj ); + [PreserveSig] + HRESULT SetHostNames([MarshalAs(UnmanagedType.LPWStr)] string szContainerApp, [MarshalAs(UnmanagedType.LPWStr)] string szContainerObj); + + /// Changes an embedded object from the running to the loaded state. Disconnects a linked object from its link source. + /// + /// + /// Indicates whether the object is to be saved as part of the transition to the loaded state. Valid values are taken from the + /// enumeration OLECLOSE. + /// + /// + /// Note The OLE 2 user model recommends that object applications do not prompt users before saving linked or embedded + /// objects, including those activated in place. This policy represents a change from the OLE 1 user model, in which object + /// applications always prompt the user to decide whether to save changes. + /// + /// + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// OLE_E_PROMPTSAVECANCELLED + /// The user was prompted to save but chose the Cancel button from the prompt message box. + /// + /// + /// + /// + /// Notes to Callers + /// + /// A container application calls IOleObject::Close when it wants to move the object from a running to a loaded state. + /// Following such a call, the object still appears in its container but is not open for editing. Calling + /// IOleObject::Close on an object that is loaded but not running has no effect. Closing a linked object simply means + /// disconnecting it. + /// + /// Notes to Implementers + /// Upon receiving a call to IOleObject::Close, a running object should do the following: + /// + /// + /// + /// If the object has been changed since it was last opened for editing, it should request to be saved, or not, according to + /// instructions specified in dwSaveOption. If the option is to save the object, then it should call its container's + /// IOleClientSite::SaveObject interface. + /// + /// + /// + /// + /// If the object has IDataObject::DAdvise connections with ADVF_DATAONSTOP flags, then it should send an + /// IAdviseSink::OnDataChange notification. See IDataObject::DAdvise for details. + /// + /// + /// + /// If the object currently owns the Clipboard, it should empty it by calling OleFlushClipboard. + /// + /// + /// + /// If the object is currently visible, notify its container by calling IOleClientSite::OnShowWindow with the fshow argument set + /// to FALSE. + /// + /// + /// + /// Send IAdviseSink::OnClose notifications to appropriate advise sinks. + /// + /// + /// Finally, forcibly cut off all remoting clients by calling CoDisconnectObject. + /// + /// + /// + /// If the object application is a local server (an EXE rather than a DLL), closing the object should also shut down the object + /// application unless the latter is supporting other running objects or has another reason to remain in the running state. Such + /// reasons might include the presence of IClassFactory::LockServer locks, end-user control of the application, or the existence + /// of other open documents requiring access to the application. + /// + /// + /// Calling IOleObject::Close on a linked object disconnects it from, but does not shut down, its source application. A + /// source application that is visible to the user when the object is closed remains visible and running after the disconnection + /// and does not send an IAdviseSink::OnClose notification to the link container. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleobject-close HRESULT Close( DWORD dwSaveOption ); + [PreserveSig] + HRESULT Close(OLECLOSE dwSaveOption); + + /// + /// Notifies an object of its container's moniker, the object's own moniker relative to the container, or the object's full moniker. + /// + /// The moniker is passed in pmk. Possible values are from the enumeration OLEWHICHMK. + /// Pointer to where to return the moniker. + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// E_FAIL + /// The operation failed. + /// + /// + /// + /// + /// + /// A container that supports links to embedded objects must be able to inform an embedded object when its moniker has changed. + /// Otherwise, subsequent attempts by link clients to bind to the object will fail. The IOleObject::SetMoniker method + /// provides one way for a container to communicate this information. + /// + /// + /// The container can pass either its own moniker, an object's moniker relative to the container, or an object's full moniker. + /// In practice, if a container passes anything other than an object's full moniker, each object calls the container back to + /// request assignment of the full moniker, which the object requires to register itself in the running object table. + /// + /// + /// The moniker of an object relative to its container is stored by the object handler as part of the object's persistent state. + /// The moniker of the object's container, however, must not be persistently stored inside the object because the container can + /// be renamed at any time. + /// + /// Notes to Callers + /// + /// A container calls IOleObject::SetMoniker when the container has been renamed, and the container's embedded objects + /// currently or can potentially serve as link sources. Containers call SetMoniker mainly in the context of linking because an + /// embedded object is already aware of its moniker. Even in the context of linking, calling this method is optional because + /// objects can call IOleClientSite::GetMoniker to force assignment of a new moniker. + /// + /// Notes to Implementers + /// + /// Upon receiving a call to IOleObject::SetMoniker, an object should register its full moniker in the running object + /// table and send IAdviseSink::OnRename notification to all advise sinks that exist for the object. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleobject-setmoniker HRESULT SetMoniker( DWORD + // dwWhichMoniker, IMoniker *pmk ); + [PreserveSig] + HRESULT SetMoniker(OLEWHICHMK dwWhichMoniker, IMoniker pmk); + + /// Retrieves an embedded object's moniker, which the caller can use to link to the object. + /// + /// + /// Determines how the moniker is assigned to the object. Depending on the value of dwAssign, IOleObject::GetMoniker does + /// one of the following: + /// + /// + /// + /// Obtains a moniker only if one has already been assigned. + /// + /// + /// Forces assignment of a moniker, if necessary, in order to satisfy the call. + /// + /// + /// Obtains a temporary moniker. + /// + /// + /// Values for + /// dwAssign + /// are specified in the enumeration + /// OLEGETMONIKER + /// . + /// + /// Note You cannot pass OLEGETMONIKER_UNASSIGN when calling IOleObject::GetMoniker. This value is valid only when + /// calling IOleObject::GetMoniker. + /// + /// + /// + /// Specifies the form of the moniker being requested. Possible values are taken from the enumeration OLEWHICHMK. + /// + /// + /// Address of IMoniker pointer variable that receives the interface pointer to the object's moniker. If an error occurs, ppmk + /// must be set to NULL. Each time an object receives a call to IOleObject::GetMoniker, it must increase the + /// reference count on ppmk. It is the caller's responsibility to call Release when it is done with ppmk. + /// + /// This method returns S_OK on success. + /// + /// The IOleObject::GetMoniker method returns an object's moniker. Like IOleObject::SetMoniker, this method is important + /// only in the context of managing links to embedded objects and even in that case is optional. A potential link client that + /// requires an object's moniker to bind to the object can call this method to obtain that moniker. The default implementation + /// of IOleObject::GetMoniker calls the IOleClientSite::GetMoniker, returning E_UNEXPECTED if the object is not running + /// or does not have a valid pointer to a client site. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleobject-getmoniker HRESULT GetMoniker( DWORD dwAssign, + // DWORD dwWhichMoniker, IMoniker **ppmk ); + [PreserveSig] + HRESULT GetMoniker(OLEGETMONIKER dwAssign, OLEWHICHMK dwWhichMoniker, out IMoniker ppmk); + + /// + /// Initializes a newly created object with data from a specified data object, which can reside either in the same container or + /// on the Clipboard. + /// + /// + /// Pointer to the IDataObject interface on the data object from which the initialization data is to be obtained. This parameter + /// can be NULL, which indicates that the caller wants to know if it is worthwhile trying to send data; that is, whether + /// the container is capable of initializing an object from data passed to it. The data object to be passed can be based on + /// either the current selection within the container document or on data transferred to the container from an external source. + /// + /// + /// TRUE indicates the container is inserting a new object inside itself and initializing that object with data from the + /// current selection; FALSE indicates a more general programmatic data transfer, most likely from a source other than + /// the current selection. + /// + /// This parameter is reserved and must be zero. + /// + /// + /// This method returns S_OK if pDataObject is not NULL, the object successfully attempted to initialize itself from the + /// provided data; if pDataObject is NULL, the object is able to attempt a successful initialization.. Other possible + /// return values include the following. + /// + /// + /// + /// Return code + /// Description + /// + /// + /// S_FALSE + /// + /// If pDataObject is not NULL, the object made no attempt to initialize itself; if pDataObject is NULL, the object cannot + /// attempt to initialize itself from the data provided. + /// + /// + /// + /// E_NOTIMPL + /// The object does not support InitFromData. + /// + /// + /// OLE_E_NOTRUNNING + /// The object is not running and therefore cannot perform the operation. + /// + /// + /// + /// + /// + /// This method enables a container document to insert within itself a new object whose content is based on a current data + /// selection within the container. For example, a spreadsheet document may want to create a graph object based on data in a + /// selected range of cells. + /// + /// + /// Using this method, a container can also replace the contents of an embedded object with data transferred from another + /// source. This provides a convenient way of updating an embedded object. + /// + /// Notes to Callers + /// + /// Following initialization, the container should call IOleObject::GetMiscStatus to check the value of the + /// OLEMISC_INSERTNOTREPLACE bit. If the bit is on, the new object inserts itself following the selected data. If the bit is + /// off, the new object replaces the selected data. + /// + /// Notes to Implementers + /// + /// A container specifies whether to base a new object on the current selection by passing either TRUE or FALSE to + /// the fCreation parameter. + /// + /// + /// If fCreation is TRUE, the container is attempting to create a new instance of an object, initializing it with the + /// selected data specified by the data object. + /// + /// + /// If fCreation is FALSE, the caller is attempting to replace the object's current contents with that pointed to by + /// pDataObject. The usual constraints that apply to an object during a paste operation should be applied here. For example, if + /// the type of the data provided is unacceptable, the object should fail to initialize and return S_FALSE. + /// + /// If the object returns S_FALSE, it cannot initialize itself from the provided data. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleobject-initfromdata HRESULT InitFromData( IDataObject + // *pDataObject, BOOL fCreation, DWORD dwReserved ); + [PreserveSig] + HRESULT InitFromData(IDataObject pDataObject, [MarshalAs(UnmanagedType.Bool)] bool fCreation, uint dwReserved = 0); + + /// + /// Retrieves a data object containing the current contents of the embedded object on which this method is called. Using the + /// pointer to this data object, it is possible to create a new embedded object with the same data as the original. + /// + /// This parameter is reserved and must be zero. + /// + /// Address of IDataObject pointer variable that receives the interface pointer to the data object. If an error occurs, + /// ppDataObject must be set to NULL. Each time an object receives a call to IOleObject::GetClipboardData, it must + /// increase the reference count on ppDataObject. It is the caller's responsibility to call Release when it is done with ppDataObject. + /// + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// E_NOTIMPL + /// GetClipboardData is not supported. + /// + /// + /// OLE_E_NOTRUNNING + /// The object is not running. + /// + /// + /// + /// + /// + /// You can use the IOleObject::GetClipboardData method to convert a linked object to an embedded object, in which case + /// the container application would call IOleObject::GetClipboardData and then pass the data received to + /// OleCreateFromData. This method returns a pointer to a data object that is identical to what would have been passed to the + /// clipboard by a standard copy operation. + /// + /// Notes to Callers + /// + /// If you want a stable snapshot of the current contents of an embedded object, call IOleObject::GetClipboardData. + /// Should the data change, you will need to call the function again for an updated snapshot. If you want the caller to be + /// informed of changes that occur to the data, call QueryInterface, then call IDataObject::DAdvise. + /// + /// Notes to Implementers + /// If you implement this function, you must return an IDataObject pointer for an object whose data will not change. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleobject-getclipboarddata HRESULT GetClipboardData( + // DWORD dwReserved, IDataObject **ppDataObject ); + [PreserveSig] + HRESULT GetClipboardData([Optional] uint dwReserved, out IDataObject ppDataObject); + + /// + /// Requests that an object perform an action in response to an end-user's action. The possible actions are enumerated for the + /// object in IOleObject::EnumVerbs. + /// + /// Number assigned to the verb in the OLEVERB structure returned by IOleObject::EnumVerbs. + /// + /// Pointer to the MSG structure describing the event (such as a double-click) that invoked the verb. The caller should pass the + /// MSG structure unmodified, without attempting to interpret or alter the values of any of the structure members. + /// + /// + /// Pointer to the IOleClientSite interface on the object's active client site, where the event occurred that invoked the verb. + /// + /// This parameter is reserved and must be zero. + /// + /// Handle of the document window containing the object. This and lprcPosRect together make it possible to open a temporary + /// window for an object, where hwndParent is the parent window in which the object's window is to be displayed, and lprcPosRect + /// defines the area available for displaying the object window within that parent. A temporary window is useful, for example, + /// to a multimedia object that opens itself for playback but not for editing. + /// + /// + /// Pointer to the RECT structure containing the coordinates, in pixels, that define an object's bounding rectangle in + /// hwndParent. This and hwndParent together enable opening multimedia objects for playback but not for editing. + /// + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// OLE_E_NOT_INPLACEACTIVE + /// iVerb set to OLEIVERB_UIACTIVATE or OLEIVERB_INPLACEACTIVATE and object is not already visible. + /// + /// + /// OLE_E_CANT_BINDTOSOURCE + /// The object handler or link object cannot connect to the link source. + /// + /// + /// DV_E_LINDEX + /// Invalid lindex. + /// + /// + /// OLEOBJ_S_CANNOT_DOVERB_NOW + /// The verb is valid, but in the object's current state it cannot carry out the corresponding action. + /// + /// + /// OLEOBJ_S_INVALIDHWND + /// DoVerb was successful but hwndParent is invalid. + /// + /// + /// OLEOBJ_E_NOVERBS + /// The object does not support any verbs. + /// + /// + /// OLEOBJ_S_INVALIDVERB + /// Link source is across a network that is not connected to a drive on this computer. + /// + /// + /// MK_E_CONNECT + /// Link source is across a network that is not connected to a drive on this computer. + /// + /// + /// OLE_E_CLASSDIFF + /// Class for source of link has undergone a conversion. + /// + /// + /// E_NOTIMPL + /// Object does not support in-place activation or does not recognize a negative verb number. + /// + /// + /// + /// + /// + /// A "verb" is an action that an OLE object takes in response to a message from its container. An object's container, or a + /// client linked to the object, normally calls IOleObject::DoVerb in response to some end-user action, such as + /// double-clicking on the object. The various actions that are available for a given object are enumerated in an OLEVERB + /// structure, which the container obtains by calling IOleObject::EnumVerbs. IOleObject::DoVerb matches the value of + /// iVerb against the iVerb member of the structure to determine which verb to invoke. + /// + /// + /// Through IOleObject::EnumVerbs, an object, rather than its container, determines which verbs (i.e., actions) it supports. OLE + /// 2 defines seven verbs that are available, but not necessarily useful, to all objects. In addition, each object can define + /// additional verbs that are unique to it. The following table describes the verbs defined by OLE. + /// + /// + /// + /// Verb + /// Description + /// + /// + /// OLEIVERB_PRIMARY (0L) + /// + /// Specifies the action that occurs when an end user double-clicks the object in its container. The object, not the container, + /// determines this action. If the object supports in-place activation, the primary verb usually activates the object in place. + /// + /// + /// + /// OLEIVERB_SHOW (-1) + /// + /// Instructs an object to show itself for editing or viewing. Called to display newly inserted objects for initial editing and + /// to show link sources. Usually an alias for some other object-defined verb. + /// + /// + /// + /// OLEIVERB_OPEN (-2) + /// + /// Instructs an object, including one that otherwise supports in-place activation, to open itself for editing in a window + /// separate from that of its container. If the object does not support in-place activation, this verb has the same semantics as OLEIVERB_SHOW. + /// + /// + /// + /// OLEIVERB_HIDE (-3) + /// Causes an object to remove its user interface from the view. Applies only to objects that are activated in-place. + /// + /// + /// OLEIVERB_UIACTIVATE (-4) + /// + /// Activates an object in place, along with its full set of user-interface tools, including menus, toolbars, and its name in + /// the title bar of the container window. If the object does not support in-place activation, it should return E_NOTIMPL. + /// + /// + /// + /// OLEIVERB_INPLACEACTIVATE (-5) + /// + /// Activates an object in place without displaying tools, such as menus and toolbars, that end users need to change the + /// behavior or appearance of the object. Single-clicking such an object causes it to negotiate the display of its + /// user-interface tools with its container. If the container refuses, the object remains active but without its tools displayed. + /// + /// + /// + /// OLEIVERB_DISCARDUNDOSTATE (-6) + /// Used to tell objects to discard any undo state that they may be maintaining without deactivating the object. + /// + /// + /// Notes to Callers + /// + /// Containers call IOleObject::DoVerb as part of initializing a newly created object. Before making the call, containers + /// should first call IOleObject::SetClientSite to inform the object of its display location and IOleObject::SetHostNames to + /// alert the object that it is an embedded object and to trigger appropriate changes to the user interface of the object + /// application in preparation for opening an editing window. + /// + /// + /// IOleObject::DoVerb automatically runs the OLE server application. If an error occurs during verb execution, the + /// object application is shut down. + /// + /// + /// If an end user invokes a verb by some means other than selecting a command from a menu (say, by double-clicking or, more + /// rarely, single-clicking an object), the object's container should pass a pointer to a Windows MSG structure containing the + /// appropriate message. For example, if the end user invokes a verb by double-clicking the object, the container should pass a + /// MSG structure containing WM_LBUTTONDBLCLK, WM_MBUTTONDBLCLK, or WM_RBUTTONDBLCLK. If the container passes no message, + /// lpmsg should be set to NULL. The object should ignore the hwnd member of the passed MSG structure, but + /// can use all the other MSG members. + /// + /// + /// If the object's embedding container calls IOleObject::DoVerb, the client-site pointer (pClientSite) passed to + /// IOleObject::DoVerb is the same as that of the embedding site. If the embedded object is a link source, the pointer + /// passed to IOleObject::DoVerb is that of the linking client's client site. + /// + /// + /// When IOleObject::DoVerb is invoked on an OLE link, it may return OLE_E_CLASSDIFF or MK_CONNECTMANUALLY. The link + /// object returns the former error when the link source has been subjected to some sort of conversion while the link was + /// passive. The link object returns the latter error when the link source is located on a network drive that is not currently + /// connected to the caller's computer. The only way to connect a link under these conditions is to first call + /// IUnknown::QueryInterface, ask for IOleLink, allocate a bind context, and run the link source by calling IOleLink::BindToSource. + /// + /// + /// Container applications that do not support general in-place activation can still use the hwndParent and lprcPosRect + /// parameters to support in-place playback of multimedia files. Containers must pass valid hwndParent and lprcPosRect + /// parameters to IOleObject::DoVerb. + /// + /// + /// Some code samples pass a lindex value of -1 instead of zero. The value -1 works but should be avoided in favor of zero. The + /// lindex parameter is a reserved parameter, and for reasons of consistency Microsoft recommends assigning a zero value to all + /// reserved parameters. + /// + /// Notes to Implementers + /// + /// In addition to the above verbs, an object can define in its OLEVERB structure additional verbs that are specific to itself. + /// Positive numbers designate these object-specific verbs. An object should treat any unknown positive verb number as if it + /// were the primary verb and return OLEOBJ_S_INVALIDVERB to the calling function. The object should ignore verbs with negative + /// numbers that it does not recognize and return E_NOTIMPL. + /// + /// + /// If the verb being executed places the object in the running state, you should register the object in the running object + /// table (ROT) even if its server application doesn't support linking. Registration is important because the object at some + /// point may serve as the source of a link in a container that supports links to embeddings. Registering the object with the + /// ROT enables the link client to get a pointer to the object directly, instead of having to go through the object's container. + /// To perform the registration, call IOleClientSite::GetMoniker to get the full moniker of the object, call the + /// GetRunningObjectTable function to get a pointer to the ROT, and then call IRunningObjectTable::Register. + /// + /// + /// Note When the object leaves the running state, remember to revoke the object's registration with the ROT by calling + /// IOleObject::Close. If the object's container document is renamed while the object is running, you should revoke the object's + /// registration and re-register it with the ROT, using its new name. The container should inform the object of its new moniker + /// either by calling IOleObject::SetMoniker or by responding to the object's calling IOleClientSite::GetMoniker. + /// + /// + /// When showing a window as a result of IOleObject::DoVerb, it is very important for the object to explicitly call + /// SetForegroundWindow on its editing window. This ensures that the object's window will be visible to the user even if another + /// process originally obscured it. For more information see SetForegroundWindow and SetActiveWindow. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleobject-doverb HRESULT DoVerb( LONG iVerb, LPMSG + // lpmsg, IOleClientSite *pActiveSite, LONG lindex, HWND hwndParent, LPCRECT lprcPosRect ); + [PreserveSig] + HRESULT DoVerb(int iVerb, in MSG lpmsg, IOleClientSite pActiveSite, [Optional] int lindex, HWND hwndParent, in RECT lprcPosRect); + + /// Exposes a pull-down menu listing the verbs available for an object in ascending order by verb number. + /// + /// Address of IEnumOLEVERB pointer variable that receives the interface pointer to the new enumerator object. Each time an + /// object receives a call to IOleObject::EnumVerbs, it must increase the reference count on ppEnumOleVerb. It is the caller's + /// responsibility to call IUnknown::Release when it is done with ppEnumOleVerb. If an error occurs, ppEnumOleVerb must be set + /// to NULL. + /// + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// OLE_S_USEREG + /// Delegate to the default handler to use the entries in the registry to provide the enumeration. + /// + /// + /// OLEOBJ_E_NOVERBS + /// The object does not support any verbs. + /// + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleobject-enumverbs HRESULT EnumVerbs( IEnumOLEVERB + // **ppEnumOleVerb ); + [PreserveSig] + HRESULT EnumVerbs(out IEnumOLEVERB ppEnumOleVerb); + + /// Updates an object handler's or link object's data or view caches. + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// E_FAIL + /// The operation failed. + /// + /// + /// OLE_E_CANT_BINDTOSOURCE + /// Cannot run object to get updated data. The object is for some reason unavailable to the caller. + /// + /// + /// CACHE_E_NOCACHE_UPDATED + /// No caches were updated. + /// + /// + /// CACHE_S_SOMECACHES_NOTUPDATED + /// Some caches were not updated. + /// + /// + /// + /// + /// + /// The Update method provides a way for containers to keep data updated in their linked and embedded objects. A link + /// object can become out-of-date if the link source has been updated. An embedded object that contains links to other objects + /// can also become out of date. An embedded object that does not contain links cannot become out of date because its data is + /// not linked to another source. + /// + /// Notes to Implementers + /// + /// When a container calls a link object's IOleObject::Update method, the link object finds the link source and gets a + /// new presentation from it. This process may also involve running one or more object applications, which could be time-consuming. + /// + /// + /// When a container calls an embedded object's IOleObject::Update method, it is requesting the object to update all link + /// objects it may contain. In response, the object handler recursively calls IOleObject::Update for each of its own + /// linked objects, running each one as needed. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleobject-update HRESULT Update( ); + [PreserveSig] + HRESULT Update(); + + /// Checks whether an object is up to date. + /// + /// + /// This method returns S_OK if the object is up to date; otherwise, S_FALSE. Other possible return values include the following. + /// + /// + /// + /// Return code + /// Description + /// + /// + /// OLE_E_UNAVAILABLE + /// The status of object cannot be determined in a timely manner. + /// + /// + /// + /// + /// + /// The IOleObject::IsUpToDate method provides a way for containers to check recursively whether all objects are up to + /// date. That is, when the container calls this method on the first object, the object in turn calls it for all its own + /// objects, and they in turn for all of theirs, until all objects have been checked. + /// + /// Notes to Implementers + /// + /// Because of the recursive nature of IOleObject::IsUpToDate, determining whether an object is out-of-date, particularly + /// one containing one or more other objects, can be as time-consuming as simply updating the object in the first place. If you + /// would rather avoid lengthy queries of this type, make sure that IOleObject::IsUpToDate returns OLE_E_UNAVAILABLE. In + /// cases where the object to be queried is small and contains no objects itself, thereby making an efficient query possible, + /// this method can return either S_OK or S_FALSE. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleobject-isuptodate HRESULT IsUpToDate( ); + [PreserveSig] + HRESULT IsUpToDate(); + + /// + /// Retrieves an object's class identifier, the CLSID corresponding to the string identifying the object to an end user. + /// + /// + /// Pointer to the class identifier (CLSID) to be returned. An object's CLSID is the binary equivalent of the user-type name + /// returned by IOleObject::GetUserType. + /// + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// E_FAIL + /// The operation failed. + /// + /// + /// + /// + /// IOleObject::GetUserClassID returns the CLSID associated with the object in the registration database. Normally, this + /// value is identical to the CLSID stored with the object, which is returned by IPersist::GetClassID. For linked objects, this + /// is the CLSID of the last bound link source. If the object is running in an application different from the one in which it + /// was created and for the purpose of being edited is emulating a class that the container application recognizes, the CLSID + /// returned will be that of the class being emulated rather than that of the object's own class. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleobject-getuserclassid HRESULT GetUserClassID( CLSID + // *pClsid ); + [PreserveSig] + HRESULT GetUserClassID(out Guid pClsid); + + /// + /// Retrieves the user-type name of an object for display in user-interface elements such as menus, list boxes, and dialog boxes. + /// + /// + /// The form of the user-type name to be presented to users. Possible values are obtained from the USERCLASSTYPE enumeration. + /// + /// + /// Address of LPOLESTR pointer variable that receives a pointer to the user type string. The caller must free pszUserType using + /// the current IMalloc instance. If an error occurs, the implementation must set pszUserType to NULL. + /// + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// OLE_S_USEREG + /// Delegate to the default handler's implementation using the registry to provide the requested information. + /// + /// + /// + /// + /// + /// Containers call IOleObject::GetUserType in order to represent embedded objects in list boxes, menus, and dialog boxes + /// by their normal, user-recognizable names. Examples include "Word Document," "Excel Chart," and "Paintbrush Object." The + /// information returned by IOleObject::GetUserType is the user-readable equivalent of the binary class identifier + /// returned by IOleObject::GetUserClassID. + /// + /// Notes to Callers + /// + /// The default handler's implementation of IOleObject::GetUserType uses the object's class identifier (the pClsid + /// parameter returned by IOleObject::GetUserClassID) and the dwFormOfType parameter together as a key into the registry. If an + /// entry is found that matches the key exactly, then the user type specified by that entry is returned. If only the CLSID part + /// of the key matches, then the lowest-numbered entry available (usually the full name) is used. If the CLSID is not found, or + /// there are no user types registered for the class, the user type currently found in the object's storage is used. + /// + /// + /// You should not cache the string returned from IOleObject::GetUserType. Instead, call this method each and every time + /// the string is needed. This guarantees correct results when the embedded object is being converted from one type into another + /// without the caller's knowledge. Calling this method is inexpensive because the default handler implements it using the registry. + /// + /// Notes to Implementers + /// + /// You can use the implementation provided by the default handler by returning OLE_S_USEREG as your application's + /// implementation of this method. If the user type name is an empty string, the message "Unknown Object" is returned. + /// + /// You can call the OLE helper function OleRegGetUserType to return the appropriate user type. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleobject-getusertype HRESULT GetUserType( DWORD + // dwFormOfType, LPOLESTR *pszUserType ); + [return: MarshalAs(UnmanagedType.LPWStr)] + [PreserveSig] + HRESULT GetUserType(USERCLASSTYPE dwFormOfType, [MarshalAs(UnmanagedType.LPWStr)] out string pszUserType); + + /// Informs an object of how much display space its container has assigned it. + /// + /// DWORD that describes which form, or "aspect," of an object is to be displayed. The object's container obtains this value + /// from the enumeration DVASPECT (refer to the FORMATETC enumeration). The most common aspect is DVASPECT_CONTENT, which + /// specifies a full rendering of the object within its container. An object can also be rendered as an icon, a thumbnail + /// version for display in a browsing tool, or a print version, which displays the object as it would be rendered using the + /// File Print command. + /// + /// Pointer to the size limit for the object. + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// E_FAIL + /// The operation failed. + /// + /// + /// OLE_E_NOTRUNNING + /// The object is not running. + /// + /// + /// + /// + /// + /// A container calls IOleObject::SetExtent when it needs to dictate to an embedded object the size at which it will be + /// displayed. Often, this call occurs in response to an end user resizing the object window. Upon receiving the call, the + /// object, if possible, should recompose itself gracefully to fit the new window. + /// + /// + /// Whenever possible, a container seeks to display an object at its finest resolution, sometimes called the object's native + /// size. All objects, however, have a default display size specified by their applications, and in the absence of other + /// constraints, this is the size they will use to display themselves. Since an object knows its optimum display size better + /// than does its container, the latter normally requests that size from a running object by calling + /// IOleObject::SetExtent. Only in cases where the container cannot accommodate the value returned by the object does it + /// override the object's preference by calling IOleObject::SetExtent. + /// + /// Notes to Callers + /// + /// You can call IOleObject::SetExtent on an object only when the object is running. If a container resizes an object + /// while an object is not running, the container should keep track of the object's new size but defer calling + /// IOleObject::SetExtent until a user activates the object. If the OLEMISC_RECOMPOSEONRESIZE bit is set on an object, + /// its container should force the object to run before calling IOleObject::SetExtent. + /// + /// + /// As noted above, a container may want to delegate responsibility for setting the size of an object's display site to the + /// object itself, by calling IOleObject::SetExtent. + /// + /// Notes to Implementers + /// + /// You may want to implement this method so that your object rescales itself to match as closely as possible the maximum space + /// available to it in its container. + /// + /// + /// If an object's size is fixed, that is, if it cannot be set by its container, IOleObject::SetExtent should return + /// E_FAIL. This is always the case with linked objects, whose sizes are set by their link sources, not by their containers. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleobject-setextent HRESULT SetExtent( DWORD + // dwDrawAspect, SIZEL *psizel ); + [PreserveSig] + HRESULT SetExtent(DVASPECT dwDrawAspect, in SIZE psizel); + + /// Retrieves a running object's current display size. + /// + /// The aspect of the object whose limit is to be retrieved; the value is obtained from the enumerations DVASPECT and from + /// DVASPECT2. Note that newer objects and containers that support optimized drawing interfaces support the DVASPECT2 + /// enumeration values. Older objects and containers that do not support optimized drawing interfaces may not support + /// DVASPECT2. The most common value for this method is DVASPECT_CONTENT, which specifies a full rendering of the object + /// within its container. + /// + /// Pointer to where the object's size is to be returned. + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// E_INVALIDARG + /// The supplied dwDrawAspect value is invalid. + /// + /// + /// + /// + /// + /// A container calls IOleObject::GetExtent on a running object to retrieve its current display size. If the container + /// can accommodate that size, it will normally do so because the object, after all, knows what size it should be better than + /// the container does. A container normally makes this call as part of initializing an object. + /// + /// + /// The display size returned by IOleObject::GetExtent may differ from the size last set by IOleObject::SetExtent because + /// the latter method dictates the object's display space at the time the method is called but does not necessarily change the + /// object's native size, as determined by its application. + /// + /// + /// If one of the new aspects is requested in dwAspect, this method can either fail or return the same rectangle as for the + /// DVASPECT_CONTENT aspect. + /// + /// + /// Note This method must return the same size as DVASPECT_CONTENT for all the new aspects in DVASPECT2. + /// IViewObject2::GetExtent must do the same thing. + /// + /// Notes to Callers + /// + /// Because a container can make this call only to a running object, the container must instead call IViewObject2::GetExtent if + /// it wants to get the display size of a loaded object from its cache. + /// + /// Notes to Implementers + /// Implementation consists of filling the sizel structure with an object's height and width. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleobject-getextent HRESULT GetExtent( DWORD + // dwDrawAspect, SIZEL *psizel ); + [PreserveSig] + HRESULT GetExtent(DVASPECT dwDrawAspect, out SIZE psizel); + + /// + /// Establishes an advisory connection between a compound document object and the calling object's advise sink, through which + /// the calling object receives notification when the compound document object is renamed, saved, or closed. + /// + /// Pointer to the IAdviseSink interface on the advise sink of the calling object. + /// Pointer to a token that can be passed to IOleObject::Unadvise to delete the advisory connection. + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// E_OUTOFMEMORY + /// Insufficient memory available for this operation. + /// + /// + /// + /// + /// + /// The IOleObject::Advise method sets up an advisory connection between an object and its container, through which the + /// object informs the container's advise sink of close, save, rename, and link-source change events in the object. A container + /// calls this method, normally as part of initializing an object, to register its advisory sink with the object. In return, the + /// object sends the container compound-document notifications by calling IAdviseSink or IAdviseSink2. + /// + /// + /// If container and object successfully establish an advisory connection, the object receiving the call returns a nonzero value + /// through pdwConnection to the container. If the attempt to establish an advisory connection fails, the object returns zero. + /// To delete an advisory connection, the container calls IOleObject::Unadvise and passes this nonzero token back to the object. + /// + /// + /// An object can delegate the job of managing and tracking advisory events to an OLE advise holder, to which you obtain a + /// pointer by calling CreateOleAdviseHolder. The returned IOleAdviseHolder interface has three methods for sending advisory + /// notifications, as well as IOleAdviseHolder::Advise, IOleAdviseHolder::Unadvise, and IOleAdviseHolder::EnumAdvise methods + /// that are identical to those for IOleObject. Calls to IOleObject::Advise, IOleObject::Unadvise, or + /// IOleObject::EnumAdvise are delegated to corresponding methods in the advise holder. + /// + /// To destroy the advise holder, simply call IUnknown::Release on the IOleAdviseHolder interface. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleobject-advise HRESULT Advise( IAdviseSink *pAdvSink, + // DWORD *pdwConnection ); + [PreserveSig] + HRESULT Advise(IAdviseSink pAdvSink, out uint pdwConnection); + + /// Deletes a previously established advisory connection. + /// + /// Contains a token of nonzero value, which was previously returned from IOleObject::Advise through its pdwConnection parameter. + /// + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// E_FAIL + /// The operation failed. + /// + /// + /// OLE_E_NOCONNECTION + /// dwConnection does not represent a valid advisory connection. + /// + /// + /// + /// + /// Normally, containers call IOleObject::Unadvise at shutdown or when an object is deleted. In certain cases, containers + /// can call this method on objects that are running but not currently visible as a way of reducing the overhead of maintaining + /// multiple advisory connections. The easiest way to implement this method is to delegate the call to IOleObject::Unadvise. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleobject-unadvise HRESULT Unadvise( DWORD dwConnection ); + [PreserveSig] + HRESULT Unadvise(uint dwConnection); + + /// + /// Retrieves a pointer to an enumerator that can be used to enumerate the advisory connections registered for an object, so a + /// container can know what to release prior to closing down. + /// + /// + /// Address of IEnumSTATDATA pointer variable that receives the interface pointer to the enumerator object. If the object does + /// not have any advisory connections or if an error occurs, the implementation must set ppenumAdvise to NULL. Each time an + /// object receives a successful call to IOleObject::EnumAdvise, it must increase the reference count on ppenumAdvise. It is the + /// caller's responsibility to call Release when it is done with the ppenumAdvise. + /// + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// E_NOTIMPL + /// EnumAdvise is not supported. + /// + /// + /// + /// + /// + /// The IOleObject::EnumAdvise method supplies an enumerator that provides a way for containers to keep track of advisory + /// connections registered for their objects. A container normally would call this function so that it can instruct an object to + /// release each of its advisory connections prior to closing down. + /// + /// + /// The enumerator to which you get access through IOleObject::EnumAdvise enumerates items of type STATDATA. Upon + /// receiving the pointer, the container can then loop through STATDATA and call IOleObject::Unadvise for each enumerated connection. + /// + /// + /// The usual way to implement this function is to delegate the call to the IOleAdviseHolder interface. Only the pAdvise + /// and dwConnection members of STATDATA are relevant for IOleObject::EnumAdvise. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleobject-enumadvise HRESULT EnumAdvise( IEnumSTATDATA + // **ppenumAdvise ); + [PreserveSig] + HRESULT EnumAdvise(out IEnumSTATDATA ppenumAdvise); + + /// Retrieves the status of an object at creation and loading. + /// + /// The aspect of an object about which status information is being requested. The value is obtained from the enumeration DVASPECT. + /// + /// Pointer to where the status information is returned. This parameter cannot be NULL. + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// OLE_S_USEREG + /// Delegate the retrieval of miscellaneous status information to the default handler's implementation of this method. + /// + /// + /// CO_E_CLASSNOTREG + /// There is no CLSID registered for the object. + /// + /// + /// CO_E_READREGDB + /// Error accessing the registry. + /// + /// + /// + /// + /// + /// A container normally calls IOleObject::GetMiscStatus when it creates or loads an object in order to determine how to + /// display the object and what types of behaviors it supports. + /// + /// + /// Objects store status information in the registry. If the object is not running, the default handler's implementation of + /// IOleObject::GetMiscStatus retrieves this information from the registry. If the object is running, the default handler + /// invokes IOleObject::GetMiscStatus on the object itself. + /// + /// + /// The information that is actually stored in the registry varies with individual objects. The status values to be returned are + /// defined in the enumeration OLEMISC. + /// + /// + /// The default value of IOleObject::GetMiscStatus is used if a subkey corresponding to the specified DVASPECT is not + /// found. To set an OLE control, specify DVASPECT==1. This will cause the following to occur in the registry: + /// + /// HKEY_CLASSES_ROOT\CLSID\ . . .MiscStatus = 1 + /// Notes to Implementers + /// Implementation normally consists of delegating the call to the default handler. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleobject-getmiscstatus HRESULT GetMiscStatus( DWORD + // dwAspect, DWORD *pdwStatus ); + [PreserveSig] + HRESULT GetMiscStatus(DVASPECT dwAspect, out uint pdwStatus); + + /// Specifies the color palette that the object application should use when it edits the specified object. + /// Pointer to a LOGPALETTE structure that specifies the recommended palette. + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// E_NOTIMPL + /// Object does not support setting palettes. + /// + /// + /// OLE_E_PALETTE + /// Invalid LOGPALETTE structure pointed to by pLogPal. + /// + /// + /// OLE_E_NOTRUNNING + /// Object must be running to perform this operation. + /// + /// + /// + /// + /// The IOleObject::SetColorScheme method sends the container application's recommended color palette to the object + /// application, which is not obliged to use it. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-ioleobject-setcolorscheme HRESULT SetColorScheme( + // LOGPALETTE *pLogpal ); + [PreserveSig] + HRESULT SetColorScheme([In, MarshalAs(UnmanagedType.CustomMarshaler, MarshalTypeRef = typeof(VanaraCustomMarshaler))] LOGPALETTE pLogpal); + } + + /// + /// The IOleWindow interface provides methods that allow an application to obtain the handle to the various windows that participate + /// in in-place activation, and also to enter and exit context-sensitive help mode. + /// + [PInvokeData("Oleidl.h")] + [ComImport, Guid("00000114-0000-0000-C000-000000000046"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IOleWindow + { + /// + /// Retrieves a handle to one of the windows participating in in-place activation (frame, document, parent, or in-place object window). + /// + /// A pointer to a variable that receives the window handle. + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// E_FAIL + /// The object is windowless. + /// + /// + /// E_OUTOFMEMORY + /// There is insufficient memory available for this operation. + /// + /// + /// E_UNEXPECTED + /// An unexpected error has occurred. + /// + /// + /// + /// + /// + /// Five types of windows comprise the windows hierarchy. When a object is active in place, it has access to some or all of + /// these windows. + /// + /// + /// + /// Window + /// Description + /// + /// + /// Frame + /// The outermost main window where the container application's main menu resides. + /// + /// + /// Document + /// The window that displays the compound document containing the embedded object to the user. + /// + /// + /// Pane + /// + /// The subwindow of the document window that contains the object's view. Applicable only for applications with split-pane windows. + /// + /// + /// + /// Parent + /// + /// The container window that contains that object's view. The object application installs its window as a child of this window. + /// + /// + /// + /// In-place + /// + /// The window containing the active in-place object. The object application creates this window and installs it as a child of + /// its hatch window, which is a child of the container's parent window. + /// + /// + /// + /// + /// Each type of window has a different role in the in-place activation architecture. However, it is not necessary to employ a + /// separate physical window for each type. Many container applications use the same window for their frame, document, pane, and + /// parent windows. + /// + /// + [PreserveSig] + HRESULT GetWindow(out HWND phwnd); + + /// Determines whether context-sensitive help mode should be entered during an in-place activation session. + /// + /// if help mode should be entered; if it should be exited. + /// + /// + /// + /// This method returns S_OK if the help mode was entered or exited successfully, depending on the value passed in . Other possible return values include the following.
+ /// + /// + /// + /// Return code + /// Description + /// + /// + /// E_INVALIDARG + /// The specified value is not valid. + /// + /// + /// E_OUTOFMEMORY + /// There is insufficient memory available for this operation. + /// + /// + /// E_UNEXPECTED + /// An unexpected error has occurred. + /// + /// + /// + /// + /// Applications can invoke context-sensitive help when the user: + /// + /// presses SHIFT+F1, then clicks a topic + /// presses F1 when a menu item is selected + /// + /// + /// When SHIFT+F1 is pressed, either the frame or active object can receive the keystrokes. If the container's frame receives + /// the keystrokes, it calls its containing document's IOleWindow::ContextSensitiveHelp method with set to . This propagates the help state to all of its in-place objects so they can + /// correctly handle the mouse click or WM_COMMAND. + /// + /// + /// If an active object receives the SHIFT+F1 keystrokes, it calls the container's IOleWindow::ContextSensitiveHelp method with + /// set to , which then recursively calls each of its in-place sites until + /// there are no more to be notified. The container then calls its document's or frame's IOleWindow::ContextSensitiveHelp method + /// with set to . + /// + /// When in context-sensitive help mode, an object that receives the mouse click can either: + /// + /// Ignore the click if it does not support context-sensitive help. + /// + /// Tell all the other objects to exit context-sensitive help mode with ContextSensitiveHelp set to FALSE and then provide help + /// for that context. + /// + /// + /// + /// An object in context-sensitive help mode that receives a WM_COMMAND should tell all the other in-place objects to exit + /// context-sensitive help mode and then provide help for the command. + /// + /// + /// If a container application is to support context-sensitive help on menu items, it must either provide its own message filter + /// so that it can intercept the F1 key or ask the OLE library to add a message filter by calling OleSetMenuDescriptor, passing + /// valid, non-NULL values for the lpFrame and lpActiveObj parameters. + /// + /// + [PreserveSig] + HRESULT ContextSensitiveHelp([MarshalAs(UnmanagedType.Bool)] bool fEnterMode); + } + + /// + /// Parses a displayable name string to convert it into a moniker for custom moniker implementations. + /// Display name parsing is necessary when the end user inputs a string to identify a component, as in the following situations: + /// + /// + /// + /// A compound document application that supports linked components typically supports the Edit:Links... dialog box. Through + /// this dialog box, the end user can enter a display name to specify a new link source for a specified linked component. The + /// compound document needs to have this input string converted into a moniker. + /// + /// + /// + /// + /// A script language such as the macro language of a spreadsheet can allow textual references to a component. The language's + /// interpreter needs to have such a reference converted into a moniker in order to execute the macro. + /// + /// + /// + /// This interface is not supported for use across machine boundaries. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nn-oleidl-iparsedisplayname + [PInvokeData("oleidl.h", MSDNShortId = "37844d9b-35ce-4d30-8a58-dac4c671896f")] + [ComImport, Guid("0000011a-0000-0000-C000-000000000046"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IParseDisplayName + { + /// Parses the specified display name and creates a corresponding moniker. + /// A pointer to the bind context to be used in this binding operation. See IBindCtx. + /// The display name to be parsed. + /// + /// A pointer to a variable that receives the number of characters in the display name that correspond to the ppmkOut moniker. + /// + /// + /// A pointer to an IMoniker pointer variable that receives the interface pointer to the resulting moniker. If an error occurs, + /// the implementation sets *ppmkOut to NULL. If *ppmkOut is non- NULL, the implementation must call AddRef; it is + /// the caller's responsibility to call Release. + /// + /// + /// This method can return the standard return values E_OUTOFMEMORY and E_UNEXPECTED, as well as the following values. + /// + /// + /// Return code + /// Description + /// + /// + /// S_OK + /// The method completed successfully. + /// + /// + /// MK_E_SYNTAX + /// + /// There is a syntax error in the display name. Parsing failed because pszDisplayName could only be partially resolved into a + /// moniker. In this case, *pchEaten has the number of characters that were successfully parsed into a moniker prefix. The + /// parameter ppmkOut should be NULL. + /// + /// + /// + /// MK_E_NOOBJECT + /// The display name does not identify a component in this namespace. + /// + /// + /// E_INVALIDARG + /// One or more parameters are not valid. + /// + /// + /// + /// + /// + /// In general, the maximum prefix of pszDisplayName that is syntactically valid and that represents an object should be + /// consumed by this method and converted to a moniker. + /// + /// + /// Typically, this method is called by MkParseDisplayName or MkParseDisplayNameEx. In the initial step of the parsing + /// operation, these functions can retrieve the IParseDisplayName interface directly from an instance of a class identified with + /// either the "@ProgID" or "ProgID" notation. Subsequent parsing steps can query for the interface on an intermediate object. + /// + /// + /// The main loops of MkParseDisplayName and MkParseDisplayNameEx find the next moniker piece by calling the equivalent method + /// in the IMoniker interface, that is, IMoniker::ParseDisplayName, on the moniker that it currently holds. In this call to + /// IMoniker::ParseDisplayName, the MkParseDisplayName or MkParseDisplayNameEx function passes NULL + /// in the pmkToLeft parameter. If the moniker currently held is a generic composite, the call to + /// IMoniker::ParseDisplayName is forwarded by that composite onto its last piece, passing the prefix of the composite to + /// the left of the piece in pmkToLeft. + /// + /// + /// Some moniker classes will be able to handle this parsing internally to themselves because they are designed to designate + /// only certain kinds of objects. Others will need to bind to the object that they designate to accomplish the parsing process. + /// As is usual, these objects should not be released by IMoniker::ParseDisplayName but instead should be transferred to the + /// bind context via IBindCtx::RegisterObjectBound or IBindCtx::GetRunningObjectTable followed by IRunningObjectTable::Register + /// for release at a later time. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iparsedisplayname-parsedisplayname HRESULT + // ParseDisplayName( IBindCtx *pbc, LPOLESTR pszDisplayName, ULONG *pchEaten, IMoniker **ppmkOut ); + [PreserveSig] + HRESULT ParseDisplayName(IBindCtx pbc, [MarshalAs(UnmanagedType.LPWStr)] string pszDisplayName, out uint pchEaten, out IMoniker ppmkOut); + } + + /// + /// + /// Enables an object to display itself directly without passing a data object to the caller. In addition, this interface can create + /// and manage a connection with an advise sink so the caller can be notified of changes in the view object. + /// + /// + /// The caller can request specific representations and specific target devices. For example, a caller can ask for either an + /// object's content or an iconic representation. Also, the caller can ask the object to compose a picture for a target device that + /// is independent of the drawing device context. As a result, the picture can be composed for one target device and drawn on + /// another device context. For example, to provide a print preview operation, you can compose the drawing for a printer target + /// device but actually draw the representation on the display. + /// + /// + /// The IViewObject interface is similar to IDataObject; except that IViewObject places a representation of the data + /// onto a device context while IDataObject places the representation onto a transfer medium. + /// + /// + /// Unlike most other interfaces, IViewObject cannot be marshaled to another process. This is because device contexts are + /// only effective in the context of one process. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nn-oleidl-iviewobject + [PInvokeData("oleidl.h", MSDNShortId = "NN:oleidl.IViewObject")] + [ComImport, Guid("0000010d-0000-0000-C000-000000000046"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IViewObject + { + /// Draws a representation of an object onto the specified device context. + /// + /// Specifies the aspect to be drawn, that is, how the object is to be represented. Representations include content, an icon, a + /// thumbnail, or a printed document. Valid values are taken from the enumerations DVASPECT and DVASPECT2. Note that newer + /// objects and containers that support optimized drawing interfaces support the DVASPECT2 enumeration values. Older + /// objects and containers that do not support optimized drawing interfaces may not support DVASPECT2. Windowless objects + /// allow only DVASPECT _CONTENT, DVASPECT _OPAQUE, and DVASPECT _TRANSPARENT. + /// + /// + /// Portion of the object that is of interest for the draw operation. Its interpretation varies depending on the value in the + /// dwAspect parameter. See the DVASPECT enumeration for more information. + /// + /// + /// Pointer to additional information in a DVASPECTINFO structure that enables drawing optimizations depending on the aspect + /// specified. Note that newer objects and containers that support optimized drawing interfaces support this parameter as well. + /// Older objects and containers that do not support optimized drawing interfaces always specify NULL for this parameter. + /// + /// + /// Pointer to the DVTARGETDEVICE structure that describes the device for which the object is to be rendered. If NULL, + /// the view should be rendered for the default target device (typically the display). A value other than NULL is + /// interpreted in conjunction with hdcTargetDev and hdcDraw. For example, if hdcDraw specifies a printer as the device context, + /// the ptd parameter points to a structure describing that printer device. The data may actually be printed if hdcTargetDev is + /// a valid value or it may be displayed in print preview mode if hdcTargetDev is NULL. + /// + /// + /// Information context for the target device indicated by the ptd parameter from which the object can extract device metrics + /// and test the device's capabilities. If ptd is NULL; the object should ignore the value in the hdcTargetDev parameter. + /// + /// + /// Device context on which to draw. For a windowless object, the hdcDraw parameter should be in MM_TEXT mapping mode with its + /// logical coordinates matching the client coordinates of the containing window. For a windowless object, the device context + /// should be in the same state as the one normally passed by a WM_PAINT message. + /// + /// + /// Pointer to a RECTL structure specifying the rectangle on hdcDraw and in which the object should be drawn. This parameter + /// controls the positioning and stretching of the object. This parameter should be NULL to draw a windowless in-place + /// active object. In every other situation, NULL is not a legal value and should result in an E_INVALIDARG error code. + /// If the container passes a non- NULL value to a windowless object, the object should render the requested aspect into + /// the specified device context and rectangle. A container can request this from a windowless object to render a second, + /// non-active view of the object or to print the object. + /// + /// + /// + /// If hdcDraw is a metafile device context, pointer to a RECTL structure specifying the bounding rectangle in the underlying + /// metafile. The rectangle structure contains the window extent and window origin. These values are useful for drawing + /// metafiles. The rectangle indicated by lprcBounds is nested inside this lprcWBounds rectangle; they are in the same + /// coordinate space. + /// + /// If hdcDraw is not a metafile device context; lprcWBounds will be NULL. + /// + /// + /// + /// Pointer to a callback function that the view object should call periodically during a lengthy drawing operation to determine + /// whether the operation should continue or be canceled. This function returns TRUE to continue drawing. It returns + /// FALSE to stop the drawing in which case IViewObject::Draw returns DRAW_E_ABORT. + /// + /// dwContinue + /// + /// + /// Value to pass as a parameter to the function pointed to by the pfnContinue parameter. Typically, dwContinue is a pointer to + /// an application-defined structure needed inside the callback function. + /// + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// OLE_E_BLANK + /// No data to draw from. + /// + /// + /// DRAW_E_ABORT + /// Draw operation aborted. + /// + /// + /// VIEW_E_DRAW + /// Error in drawing. + /// + /// + /// DV_E_LINDEX + /// Invalid value for lindex; currently only -1 is supported. + /// + /// + /// DV_E_DVASPECT + /// Invalid value for dwAspect. + /// + /// + /// OLE_E_INVALIDRECT + /// Invalid rectangle. + /// + /// + /// + /// + /// + /// A container application issues a call to IViewObject::Draw to create a representation of a contained object. This + /// method draws the specified piece (lindex) of the specified view (dwAspect and pvAspect) on the specified device context + /// (hdcDraw). Formatting, fonts, and other rendering decisions are made on the basis of the target device specified by the ptd parameter. + /// + /// + /// There is a relationship between the dwDrawAspect value and the lprcbounds value. The lprcbounds value specifies the + /// rectangle on hdcDraw into which the drawing is to be mapped. For DVASPECT_THUMBNAIL, DVASPECT _ICON, and + /// DVASPECT _SMALLICON, the object draws whatever it wants to draw, and it maps it into the space given in the best way. + /// Some objects might scale to fit while some might scale to fit but preserve the aspect ratio. In addition, some might scale + /// so the drawing appears at full width, but the bottom is cropped. The container can suggest a size via IOleObject::SetExtent, + /// but it has no control over the rendering size. In the case of DVASPECT _CONTENT, the IViewObject::Draw + /// implementation should either use the extents given by IOleObject::SetExtent or use the bounding rectangle given in + /// the lprcBounds parameter. + /// + /// + /// For newer objects that support optimized drawing techniques and for windowless objects, this method should be used as follows: + /// + /// + /// + /// New drawing aspects are supported in dwAspect as defined in DVASPECT2. + /// + /// + /// + /// The pvAspect parameter can be used to pass additional information allowing drawing optimizations through the DVASPECTINFO structure. + /// + /// + /// + /// + /// The IViewObject::Draw method can be called to redraw a windowless in-place active object by setting the lrpcBounds + /// parameter to NULL. In every other situation, NULL is an illegal value and should result in an E_INVALIDARG + /// error code. A windowless object uses the rectangle passed by the activation verb or calls IOleInPlaceObject::SetObjectRects + /// instead of using this parameter. If the container passes a non- NULL value to a windowless object, the object should + /// render the requested aspect into the specified device context and rectangle. A container can request this from a windowless + /// object to render a second, non-active view of the object or to print the object. See the IOleInPlaceSiteWindowless interface + /// for more information on drawing windowless objects. + /// + /// + /// + /// + /// For windowless objects, the dwAspect parameter only allows the DVASPECT_CONTENT, DVASPECT _OPAQUE, and + /// DVASPECT _TRANSPARENT aspects. + /// + /// + /// + /// + /// For a windowless object, the hdcDraw parameter should be in MM_TEXT mapping mode with its logical coordinates matching the + /// client coordinates of the containing window. For a windowless object, the device context should be in the same state as the + /// one normally passed by a WM_PAINT message. + /// + /// + /// + /// + /// To maintain compatibility with older objects and containers that do not support drawing optimizations, all objects, + /// rectangular or not, are required to maintain an origin and a rectangular extent. This allows the container to still consider + /// all its embedded objects as rectangles and to pass them appropriate rendering rectangles in Draw. + /// + /// + /// An object's extent depends on the drawing aspect. For non-rectangular objects, the extent should be the size of a rectangle + /// covering the entire aspect. By convention, the origin of an object is the top-left corner of the rectangle of the + /// DVASPECT_CONTENT aspect. In other words, the origin always coincides with the top-left corner of the rectangle maintained by + /// the object's site, even for a non-rectangular object. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iviewobject-draw HRESULT Draw( DWORD dwDrawAspect, LONG + // lindex, void *pvAspect, DVTARGETDEVICE *ptd, HDC hdcTargetDev, HDC hdcDraw, LPCRECTL lprcBounds, LPCRECTL lprcWBounds, BOOL(* + // )(ULONG_PTR dwContinue) pfnContinue, ULONG_PTR dwContinue ); + unsafe HRESULT Draw(DVASPECT dwDrawAspect, int lindex, [In, Optional] DVASPECTINFO* pvAspect, [In, Optional] DVTARGETDEVICE* ptd, + [In, Optional] HDC hdcTargetDev, [In] HDC hdcDraw, [In, Optional] PRECT lprcBounds, [In, Optional] PRECT lprcWBounds, + [In, Optional, MarshalAs(UnmanagedType.FunctionPtr)] Func pfnContinue, [In, Optional] IntPtr dwContinue); + + /// + /// Returns the logical palette that the object will use for drawing in its IViewObject::Draw method with the corresponding parameters. + /// + /// + /// Specifies how the object is to be represented. Representations include content, an icon, a thumbnail, or a printed document. + /// Valid values are taken from the enumeration DVASPECT. See the DVASPECT enumeration for more information. + /// + /// + /// Portion of the object that is of interest for the draw operation. Its interpretation varies with dwDrawAspect. See the + /// DVASPECT enumeration for more information. + /// + /// + /// Pointer to additional information about the view of the object specified in dwDrawAspect. Since none of the current aspects + /// support additional information, pvAspect must always be NULL. + /// + /// + /// Pointer to the DVTARGETDEVICE structure that describes the device for which the object is to be rendered. If NULL, + /// the view should be rendered for the default target device (typically the display). A value other than NULL is + /// interpreted in conjunction with hicTargetDev and hdcDraw. For example, if hdcDraw specifies a printer as the device context, + /// ptd points to a structure describing that printer device. The data may actually be printed if hicTargetDev is a valid value + /// or it may be displayed in print preview mode if hicTargetDev is NULL. + /// + /// + /// Information context for the target device indicated by the ptd parameter from which the object can extract device metrics + /// and test the device's capabilities. If ptd is NULL, the object should ignore the hicTargetDev parameter. + /// + /// + /// Address of LOGPALETTE pointer variable that receives a pointer to the LOGPALETTE structure. The LOGPALETTE structure + /// contains the set of colors that would be used if IViewObject::Draw were called with the same parameters for dwAspect, + /// lindex, pvAspect, ptd, and hicTargetDev. If ppColorSet is NULL, the object does not use a palette. + /// + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// S_FALSE + /// Set of colors is empty or the object will not give out the information. + /// + /// + /// OLE_E_BLANK + /// No presentation data for object. + /// + /// + /// DV_E_LINDEX + /// Invalid value for lindex; currently only -1 is supported. + /// + /// + /// DV_E_DVASPECT + /// Invalid value for dwAspect. + /// + /// + /// E_INVALIDARG + /// One or more of the supplied parameter values is invalid. + /// + /// + /// E_OUTOFMEMORY + /// Insufficient memory available for this operation. + /// + /// + /// + /// + /// + /// The IViewObject::GetColorSet method recursively queries any nested objects and returns a color set that represents + /// the union of all colors requested. The color set eventually percolates to the top-level container that owns the window + /// frame. This container can call IViewObject::GetColorSet on each of its embedded objects to obtain all the colors + /// needed to draw the embedded objects. The container can use the color sets obtained in conjunction with other colors it needs + /// for itself to set the overall color palette. + /// + /// + /// The OLE-provided implementation of IViewObject::GetColorSet looks at the data it has on hand to draw the picture. If + /// CF_DIB is the drawing format, the palette found in the bitmap is used. For a regular bitmap, no color information is + /// returned. If the drawing format is a metafile, the object handler enumerates the metafile looking for a CreatePalette + /// metafile record. If one is found, the handler uses it as the color set. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iviewobject-getcolorset HRESULT GetColorSet( DWORD + // dwDrawAspect, LONG lindex, void *pvAspect, DVTARGETDEVICE *ptd, HDC hicTargetDev, LOGPALETTE **ppColorSet ); + unsafe HRESULT GetColorSet(DVASPECT dwDrawAspect, int lindex, [In, Optional] DVASPECTINFO* pvAspect, [In, Optional] DVTARGETDEVICE* ptd, + [In, Optional] HDC hicTargetDev, [MarshalAs(UnmanagedType.CustomMarshaler, MarshalTypeRef = typeof(VanaraCustomMarshaler))] out LOGPALETTE ppColorSet); + + /// + /// Freezes the drawn representation of an object so that it will not change until the IViewObject::Unfreeze method is called. + /// The most common use of this method is for banded printing. + /// + /// + /// Specifies how the object is to be represented. Representations include content, an icon, a thumbnail, or a printed document. + /// Valid values are taken from the enumeration DVASPECT. See the DVASPECT enumeration for more information. + /// + /// + /// Portion of the object that is of interest for the draw operation. Its interpretation varies with dwAspect. See the DVASPECT + /// enumeration for more information. + /// + /// + /// Pointer to additional information about the view of the object specified in dwAspect. Since none of the current aspects + /// support additional information, pvAspect must always be NULL. + /// + /// + /// Pointer to where an identifying DWORD key is returned. This unique key is later used to cancel the freeze by calling + /// IViewObject::Unfreeze. This key is an index that the default cache uses to keep track of which object is frozen. + /// + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// VIEW_S_ALREADY_FROZEN + /// Presentation has already been frozen. The value of pdwFreeze is the identifying key of the already frozen object. + /// + /// + /// OLE_E_BLANK + /// Presentation not in cache. + /// + /// + /// DV_E_LINDEX + /// Invalid value for lindex; currently; only -1 is supported. + /// + /// + /// DV_E_DVASPECT + /// Invalid value for dwAspect. + /// + /// + /// + /// + /// + /// The IViewObject::Freeze method causes the view object to freeze its drawn representation until a subsequent call to + /// IViewObject::Unfreeze releases it. After calling IViewObject::Freeze, successive calls to IViewObject::Draw with the + /// same parameters produce the same picture until IViewObject::Unfreeze is called. + /// + /// + /// IViewObject::Freeze is not part of the persistent state of the object and does not continue across unloads and + /// reloads of the object. + /// + /// The most common use of this method is for banded printing. + /// + /// While in a frozen state, view notifications are not sent. Pending view notifications are deferred to the subsequent call to IViewObject::Unfreeze. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iviewobject-freeze HRESULT Freeze( DWORD dwDrawAspect, + // LONG lindex, void *pvAspect, DWORD *pdwFreeze ); + unsafe HRESULT Freeze(DVASPECT dwDrawAspect, int lindex, [In, Optional] DVASPECTINFO* pvAspect, out uint pdwFreeze); + + /// + /// Releases a drawing that was previously frozen using IViewObject::Freeze. The most common use of this method is for banded printing. + /// + /// + /// Contains a key previously returned from IViewObject::Freeze that determines which view object to unfreeze. + /// + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// OLE_E_NOCONNECTION + /// Error in the unfreezing process or the object is currently not frozen. + /// + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iviewobject-unfreeze HRESULT Unfreeze( DWORD dwFreeze ); + HRESULT Unfreeze(uint dwFreeze); + + /// + /// Establishes a connection between the view object and an advise sink so that the advise sink can be notified about changes in + /// the object's view. + /// + /// + /// View for which the advisory connection is being set up. Valid values are taken from the enumeration DVASPECT. See the + /// DVASPECT enumeration for more information. + /// + /// + /// + /// Contains a group of flags for controlling the advisory connection. Valid values are from the enumeration ADVF. However, only + /// some of the possible ADVF values are relevant for this method. The following table briefly describes the relevant + /// values. See the ADVF enumeration for a more detailed description. + /// + /// + /// + /// Value + /// Meaning + /// + /// + /// ADVF_ONLYONCE + /// Causes the advisory connection to be destroyed after the first notification is sent. + /// + /// + /// ADVF_PRIMEFIRST + /// Causes an initial notification to be sent regardless of whether data has changed from its current state. + /// + /// + /// Note The ADVF_ONLYONCE and ADVF_PRIMEFIRST can be combined to provide an asynchronous call to IDataObject::GetData. + /// + /// + /// Pointer to the IAdviseSink interface on the advisory sink that is to be informed of changes. A NULL value deletes any + /// existing advisory connection. + /// + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// OLE_E_ADVISENOTSUPPORTED + /// Advisory notifications are not supported. + /// + /// + /// DV_E_DVASPECT + /// Invalid value for dwAspect. + /// + /// + /// E_INVALIDARG + /// One or more of the supplied values is invalid. + /// + /// + /// E_OUTOFMEMORY + /// Insufficient memory available for this operation. + /// + /// + /// + /// + /// + /// A container application that is requesting a draw operation on a view object can also register with the + /// IViewObject::SetAdvise method to be notified when the presentation of the view object changes. To find out about when + /// an object's underlying data changes, you must call IDataObject::DAdvise separately. + /// + /// To remove an existing advisory connection, call the IViewObject::SetAdvise method with pAdvSink set to NULL. + /// If the view object changes, a call is made to the appropriate advise sink through its IAdviseSink::OnViewChange method. + /// + /// At any time, a given view object can support only one advisory connection. Therefore, when IViewObject::SetAdvise is + /// called and the view object is already holding on to an advise sink pointer, OLE releases the existing pointer before the new + /// one is registered. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iviewobject-setadvise HRESULT SetAdvise( DWORD aspects, + // DWORD advf, IAdviseSink *pAdvSink ); + HRESULT SetAdvise(DVASPECT aspects, ADVF advf, [In, Optional] IAdviseSink pAdvSink); + + /// Retrieves the advisory connection on the object that was used in the most recent call to IViewObject::SetAdvise. + /// + /// Pointer to where the dwAspect parameter from the previous IViewObject::SetAdvise call is returned. If this pointer is + /// NULL, the caller does not permit this value to be returned. + /// + /// + /// Pointer to where the advf parameter from the previous IViewObject::SetAdvise call is returned. If this pointer is + /// NULL, the caller does not permit this value to be returned. + /// + /// + /// Address of IAdviseSink pointer variable that receives the interface pointer to the advise sink. The connection to this + /// advise sink must have been established with a previous IViewObject::SetAdvise call, which provides the pAdvSink parameter. + /// If ppvAdvSink is NULL, there is no established advisory connection. + /// + /// This method returns S_OK on success. + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iviewobject-getadvise HRESULT GetAdvise( DWORD *pAspects, + // DWORD *pAdvf, IAdviseSink **ppAdvSink ); + unsafe HRESULT GetAdvise([Out, Optional] DVASPECT* pAspects, [Out, Optional] ADVF* pAdvf, [Out, Optional] IntPtr ppAdvSink); + } + + /// + /// + /// An extension to the IViewObject interface which returns the size of the drawing for a given view of an object. You can prevent + /// the object from being run if it isn't already running by calling this method instead of IOleObject::GetExtent. + /// + /// + /// Like the IViewObject interface, IViewObject2 cannot be marshaled to another process. This is because device contexts are + /// only effective in the context of one process. + /// + /// The OLE-provided default implementation provides the size of the object in the cache. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nn-oleidl-iviewobject2 + [PInvokeData("oleidl.h", MSDNShortId = "NN:oleidl.IViewObject2")] + [ComImport, Guid("00000127-0000-0000-C000-000000000046"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IViewObject2 : IViewObject + { + /// Draws a representation of an object onto the specified device context. + /// + /// Specifies the aspect to be drawn, that is, how the object is to be represented. Representations include content, an icon, a + /// thumbnail, or a printed document. Valid values are taken from the enumerations DVASPECT and DVASPECT2. Note that newer + /// objects and containers that support optimized drawing interfaces support the DVASPECT2 enumeration values. Older + /// objects and containers that do not support optimized drawing interfaces may not support DVASPECT2. Windowless objects + /// allow only DVASPECT _CONTENT, DVASPECT _OPAQUE, and DVASPECT _TRANSPARENT. + /// + /// + /// Portion of the object that is of interest for the draw operation. Its interpretation varies depending on the value in the + /// dwAspect parameter. See the DVASPECT enumeration for more information. + /// + /// + /// Pointer to additional information in a DVASPECTINFO structure that enables drawing optimizations depending on the aspect + /// specified. Note that newer objects and containers that support optimized drawing interfaces support this parameter as well. + /// Older objects and containers that do not support optimized drawing interfaces always specify NULL for this parameter. + /// + /// + /// Pointer to the DVTARGETDEVICE structure that describes the device for which the object is to be rendered. If NULL, + /// the view should be rendered for the default target device (typically the display). A value other than NULL is + /// interpreted in conjunction with hdcTargetDev and hdcDraw. For example, if hdcDraw specifies a printer as the device context, + /// the ptd parameter points to a structure describing that printer device. The data may actually be printed if hdcTargetDev is + /// a valid value or it may be displayed in print preview mode if hdcTargetDev is NULL. + /// + /// + /// Information context for the target device indicated by the ptd parameter from which the object can extract device metrics + /// and test the device's capabilities. If ptd is NULL; the object should ignore the value in the hdcTargetDev parameter. + /// + /// + /// Device context on which to draw. For a windowless object, the hdcDraw parameter should be in MM_TEXT mapping mode with its + /// logical coordinates matching the client coordinates of the containing window. For a windowless object, the device context + /// should be in the same state as the one normally passed by a WM_PAINT message. + /// + /// + /// Pointer to a RECTL structure specifying the rectangle on hdcDraw and in which the object should be drawn. This parameter + /// controls the positioning and stretching of the object. This parameter should be NULL to draw a windowless in-place + /// active object. In every other situation, NULL is not a legal value and should result in an E_INVALIDARG error code. + /// If the container passes a non- NULL value to a windowless object, the object should render the requested aspect into + /// the specified device context and rectangle. A container can request this from a windowless object to render a second, + /// non-active view of the object or to print the object. + /// + /// + /// + /// If hdcDraw is a metafile device context, pointer to a RECTL structure specifying the bounding rectangle in the underlying + /// metafile. The rectangle structure contains the window extent and window origin. These values are useful for drawing + /// metafiles. The rectangle indicated by lprcBounds is nested inside this lprcWBounds rectangle; they are in the same + /// coordinate space. + /// + /// If hdcDraw is not a metafile device context; lprcWBounds will be NULL. + /// + /// + /// + /// Pointer to a callback function that the view object should call periodically during a lengthy drawing operation to determine + /// whether the operation should continue or be canceled. This function returns TRUE to continue drawing. It returns + /// FALSE to stop the drawing in which case IViewObject::Draw returns DRAW_E_ABORT. + /// + /// dwContinue + /// + /// + /// Value to pass as a parameter to the function pointed to by the pfnContinue parameter. Typically, dwContinue is a pointer to + /// an application-defined structure needed inside the callback function. + /// + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// OLE_E_BLANK + /// No data to draw from. + /// + /// + /// DRAW_E_ABORT + /// Draw operation aborted. + /// + /// + /// VIEW_E_DRAW + /// Error in drawing. + /// + /// + /// DV_E_LINDEX + /// Invalid value for lindex; currently only -1 is supported. + /// + /// + /// DV_E_DVASPECT + /// Invalid value for dwAspect. + /// + /// + /// OLE_E_INVALIDRECT + /// Invalid rectangle. + /// + /// + /// + /// + /// + /// A container application issues a call to IViewObject::Draw to create a representation of a contained object. This + /// method draws the specified piece (lindex) of the specified view (dwAspect and pvAspect) on the specified device context + /// (hdcDraw). Formatting, fonts, and other rendering decisions are made on the basis of the target device specified by the ptd parameter. + /// + /// + /// There is a relationship between the dwDrawAspect value and the lprcbounds value. The lprcbounds value specifies the + /// rectangle on hdcDraw into which the drawing is to be mapped. For DVASPECT_THUMBNAIL, DVASPECT _ICON, and + /// DVASPECT _SMALLICON, the object draws whatever it wants to draw, and it maps it into the space given in the best way. + /// Some objects might scale to fit while some might scale to fit but preserve the aspect ratio. In addition, some might scale + /// so the drawing appears at full width, but the bottom is cropped. The container can suggest a size via IOleObject::SetExtent, + /// but it has no control over the rendering size. In the case of DVASPECT _CONTENT, the IViewObject::Draw + /// implementation should either use the extents given by IOleObject::SetExtent or use the bounding rectangle given in + /// the lprcBounds parameter. + /// + /// + /// For newer objects that support optimized drawing techniques and for windowless objects, this method should be used as follows: + /// + /// + /// + /// New drawing aspects are supported in dwAspect as defined in DVASPECT2. + /// + /// + /// + /// The pvAspect parameter can be used to pass additional information allowing drawing optimizations through the DVASPECTINFO structure. + /// + /// + /// + /// + /// The IViewObject::Draw method can be called to redraw a windowless in-place active object by setting the lrpcBounds + /// parameter to NULL. In every other situation, NULL is an illegal value and should result in an E_INVALIDARG + /// error code. A windowless object uses the rectangle passed by the activation verb or calls IOleInPlaceObject::SetObjectRects + /// instead of using this parameter. If the container passes a non- NULL value to a windowless object, the object should + /// render the requested aspect into the specified device context and rectangle. A container can request this from a windowless + /// object to render a second, non-active view of the object or to print the object. See the IOleInPlaceSiteWindowless interface + /// for more information on drawing windowless objects. + /// + /// + /// + /// + /// For windowless objects, the dwAspect parameter only allows the DVASPECT_CONTENT, DVASPECT _OPAQUE, and + /// DVASPECT _TRANSPARENT aspects. + /// + /// + /// + /// + /// For a windowless object, the hdcDraw parameter should be in MM_TEXT mapping mode with its logical coordinates matching the + /// client coordinates of the containing window. For a windowless object, the device context should be in the same state as the + /// one normally passed by a WM_PAINT message. + /// + /// + /// + /// + /// To maintain compatibility with older objects and containers that do not support drawing optimizations, all objects, + /// rectangular or not, are required to maintain an origin and a rectangular extent. This allows the container to still consider + /// all its embedded objects as rectangles and to pass them appropriate rendering rectangles in Draw. + /// + /// + /// An object's extent depends on the drawing aspect. For non-rectangular objects, the extent should be the size of a rectangle + /// covering the entire aspect. By convention, the origin of an object is the top-left corner of the rectangle of the + /// DVASPECT_CONTENT aspect. In other words, the origin always coincides with the top-left corner of the rectangle maintained by + /// the object's site, even for a non-rectangular object. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iviewobject-draw HRESULT Draw( DWORD dwDrawAspect, LONG + // lindex, void *pvAspect, DVTARGETDEVICE *ptd, HDC hdcTargetDev, HDC hdcDraw, LPCRECTL lprcBounds, LPCRECTL lprcWBounds, BOOL(* + // )(ULONG_PTR dwContinue) pfnContinue, ULONG_PTR dwContinue ); + new unsafe HRESULT Draw(DVASPECT dwDrawAspect, int lindex, [In, Optional] DVASPECTINFO* pvAspect, [In, Optional] DVTARGETDEVICE* ptd, + [In, Optional] HDC hdcTargetDev, [In] HDC hdcDraw, [In, Optional] PRECT lprcBounds, [In, Optional] PRECT lprcWBounds, + [In, Optional, MarshalAs(UnmanagedType.FunctionPtr)] Func pfnContinue, [In, Optional] IntPtr dwContinue); + + /// + /// Returns the logical palette that the object will use for drawing in its IViewObject::Draw method with the corresponding parameters. + /// + /// + /// Specifies how the object is to be represented. Representations include content, an icon, a thumbnail, or a printed document. + /// Valid values are taken from the enumeration DVASPECT. See the DVASPECT enumeration for more information. + /// + /// + /// Portion of the object that is of interest for the draw operation. Its interpretation varies with dwDrawAspect. See the + /// DVASPECT enumeration for more information. + /// + /// + /// Pointer to additional information about the view of the object specified in dwDrawAspect. Since none of the current aspects + /// support additional information, pvAspect must always be NULL. + /// + /// + /// Pointer to the DVTARGETDEVICE structure that describes the device for which the object is to be rendered. If NULL, + /// the view should be rendered for the default target device (typically the display). A value other than NULL is + /// interpreted in conjunction with hicTargetDev and hdcDraw. For example, if hdcDraw specifies a printer as the device context, + /// ptd points to a structure describing that printer device. The data may actually be printed if hicTargetDev is a valid value + /// or it may be displayed in print preview mode if hicTargetDev is NULL. + /// + /// + /// Information context for the target device indicated by the ptd parameter from which the object can extract device metrics + /// and test the device's capabilities. If ptd is NULL, the object should ignore the hicTargetDev parameter. + /// + /// + /// Address of LOGPALETTE pointer variable that receives a pointer to the LOGPALETTE structure. The LOGPALETTE structure + /// contains the set of colors that would be used if IViewObject::Draw were called with the same parameters for dwAspect, + /// lindex, pvAspect, ptd, and hicTargetDev. If ppColorSet is NULL, the object does not use a palette. + /// + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// S_FALSE + /// Set of colors is empty or the object will not give out the information. + /// + /// + /// OLE_E_BLANK + /// No presentation data for object. + /// + /// + /// DV_E_LINDEX + /// Invalid value for lindex; currently only -1 is supported. + /// + /// + /// DV_E_DVASPECT + /// Invalid value for dwAspect. + /// + /// + /// E_INVALIDARG + /// One or more of the supplied parameter values is invalid. + /// + /// + /// E_OUTOFMEMORY + /// Insufficient memory available for this operation. + /// + /// + /// + /// + /// + /// The IViewObject::GetColorSet method recursively queries any nested objects and returns a color set that represents + /// the union of all colors requested. The color set eventually percolates to the top-level container that owns the window + /// frame. This container can call IViewObject::GetColorSet on each of its embedded objects to obtain all the colors + /// needed to draw the embedded objects. The container can use the color sets obtained in conjunction with other colors it needs + /// for itself to set the overall color palette. + /// + /// + /// The OLE-provided implementation of IViewObject::GetColorSet looks at the data it has on hand to draw the picture. If + /// CF_DIB is the drawing format, the palette found in the bitmap is used. For a regular bitmap, no color information is + /// returned. If the drawing format is a metafile, the object handler enumerates the metafile looking for a CreatePalette + /// metafile record. If one is found, the handler uses it as the color set. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iviewobject-getcolorset HRESULT GetColorSet( DWORD + // dwDrawAspect, LONG lindex, void *pvAspect, DVTARGETDEVICE *ptd, HDC hicTargetDev, LOGPALETTE **ppColorSet ); + new unsafe HRESULT GetColorSet(DVASPECT dwDrawAspect, int lindex, [In, Optional] DVASPECTINFO* pvAspect, [In, Optional] DVTARGETDEVICE* ptd, + [In, Optional] HDC hicTargetDev, [MarshalAs(UnmanagedType.CustomMarshaler, MarshalTypeRef = typeof(VanaraCustomMarshaler))] out LOGPALETTE ppColorSet); + + /// + /// Freezes the drawn representation of an object so that it will not change until the IViewObject::Unfreeze method is called. + /// The most common use of this method is for banded printing. + /// + /// + /// Specifies how the object is to be represented. Representations include content, an icon, a thumbnail, or a printed document. + /// Valid values are taken from the enumeration DVASPECT. See the DVASPECT enumeration for more information. + /// + /// + /// Portion of the object that is of interest for the draw operation. Its interpretation varies with dwAspect. See the DVASPECT + /// enumeration for more information. + /// + /// + /// Pointer to additional information about the view of the object specified in dwAspect. Since none of the current aspects + /// support additional information, pvAspect must always be NULL. + /// + /// + /// Pointer to where an identifying DWORD key is returned. This unique key is later used to cancel the freeze by calling + /// IViewObject::Unfreeze. This key is an index that the default cache uses to keep track of which object is frozen. + /// + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// VIEW_S_ALREADY_FROZEN + /// Presentation has already been frozen. The value of pdwFreeze is the identifying key of the already frozen object. + /// + /// + /// OLE_E_BLANK + /// Presentation not in cache. + /// + /// + /// DV_E_LINDEX + /// Invalid value for lindex; currently; only -1 is supported. + /// + /// + /// DV_E_DVASPECT + /// Invalid value for dwAspect. + /// + /// + /// + /// + /// + /// The IViewObject::Freeze method causes the view object to freeze its drawn representation until a subsequent call to + /// IViewObject::Unfreeze releases it. After calling IViewObject::Freeze, successive calls to IViewObject::Draw with the + /// same parameters produce the same picture until IViewObject::Unfreeze is called. + /// + /// + /// IViewObject::Freeze is not part of the persistent state of the object and does not continue across unloads and + /// reloads of the object. + /// + /// The most common use of this method is for banded printing. + /// + /// While in a frozen state, view notifications are not sent. Pending view notifications are deferred to the subsequent call to IViewObject::Unfreeze. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iviewobject-freeze HRESULT Freeze( DWORD dwDrawAspect, + // LONG lindex, void *pvAspect, DWORD *pdwFreeze ); + new unsafe HRESULT Freeze(DVASPECT dwDrawAspect, int lindex, [In, Optional] DVASPECTINFO* pvAspect, out uint pdwFreeze); + + /// + /// Releases a drawing that was previously frozen using IViewObject::Freeze. The most common use of this method is for banded printing. + /// + /// + /// Contains a key previously returned from IViewObject::Freeze that determines which view object to unfreeze. + /// + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// OLE_E_NOCONNECTION + /// Error in the unfreezing process or the object is currently not frozen. + /// + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iviewobject-unfreeze HRESULT Unfreeze( DWORD dwFreeze ); + new HRESULT Unfreeze(uint dwFreeze); + + /// + /// Establishes a connection between the view object and an advise sink so that the advise sink can be notified about changes in + /// the object's view. + /// + /// + /// View for which the advisory connection is being set up. Valid values are taken from the enumeration DVASPECT. See the + /// DVASPECT enumeration for more information. + /// + /// + /// + /// Contains a group of flags for controlling the advisory connection. Valid values are from the enumeration ADVF. However, only + /// some of the possible ADVF values are relevant for this method. The following table briefly describes the relevant + /// values. See the ADVF enumeration for a more detailed description. + /// + /// + /// + /// Value + /// Meaning + /// + /// + /// ADVF_ONLYONCE + /// Causes the advisory connection to be destroyed after the first notification is sent. + /// + /// + /// ADVF_PRIMEFIRST + /// Causes an initial notification to be sent regardless of whether data has changed from its current state. + /// + /// + /// Note The ADVF_ONLYONCE and ADVF_PRIMEFIRST can be combined to provide an asynchronous call to IDataObject::GetData. + /// + /// + /// Pointer to the IAdviseSink interface on the advisory sink that is to be informed of changes. A NULL value deletes any + /// existing advisory connection. + /// + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// OLE_E_ADVISENOTSUPPORTED + /// Advisory notifications are not supported. + /// + /// + /// DV_E_DVASPECT + /// Invalid value for dwAspect. + /// + /// + /// E_INVALIDARG + /// One or more of the supplied values is invalid. + /// + /// + /// E_OUTOFMEMORY + /// Insufficient memory available for this operation. + /// + /// + /// + /// + /// + /// A container application that is requesting a draw operation on a view object can also register with the + /// IViewObject::SetAdvise method to be notified when the presentation of the view object changes. To find out about when + /// an object's underlying data changes, you must call IDataObject::DAdvise separately. + /// + /// To remove an existing advisory connection, call the IViewObject::SetAdvise method with pAdvSink set to NULL. + /// If the view object changes, a call is made to the appropriate advise sink through its IAdviseSink::OnViewChange method. + /// + /// At any time, a given view object can support only one advisory connection. Therefore, when IViewObject::SetAdvise is + /// called and the view object is already holding on to an advise sink pointer, OLE releases the existing pointer before the new + /// one is registered. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iviewobject-setadvise HRESULT SetAdvise( DWORD aspects, + // DWORD advf, IAdviseSink *pAdvSink ); + new HRESULT SetAdvise(DVASPECT aspects, ADVF advf, [In, Optional] IAdviseSink pAdvSink); + + /// Retrieves the advisory connection on the object that was used in the most recent call to IViewObject::SetAdvise. + /// + /// Pointer to where the dwAspect parameter from the previous IViewObject::SetAdvise call is returned. If this pointer is + /// NULL, the caller does not permit this value to be returned. + /// + /// + /// Pointer to where the advf parameter from the previous IViewObject::SetAdvise call is returned. If this pointer is + /// NULL, the caller does not permit this value to be returned. + /// + /// + /// Address of IAdviseSink pointer variable that receives the interface pointer to the advise sink. The connection to this + /// advise sink must have been established with a previous IViewObject::SetAdvise call, which provides the pAdvSink parameter. + /// If ppvAdvSink is NULL, there is no established advisory connection. + /// + /// This method returns S_OK on success. + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iviewobject-getadvise HRESULT GetAdvise( DWORD *pAspects, + // DWORD *pAdvf, IAdviseSink **ppAdvSink ); + new unsafe HRESULT GetAdvise([Out, Optional] DVASPECT* pAspects, [Out, Optional] ADVF* pAdvf, [Out, Optional] IntPtr ppAdvSink); + + /// Retrieves the size that the specified view object will be drawn on the specified target device. + /// + /// Requested view of the object whose size is of interest. Possible values are taken from the DVASPECT and DVASPECT2 + /// enumerations. Note that newer objects and containers that support optimized drawing interfaces support the DVASPECT2 + /// enumeration values. Older objects and containers that do not support optimized drawing interfaces may not support DVASPECT2. + /// + /// The portion of the object that is of interest. Currently, the only possible value is -1. + /// + /// A pointer to the DVTARGETDEVICE structure defining the target device for which the object's size should be returned. + /// + /// A pointer to where the object's size is returned. + /// + /// This method returns S_OK on success. Other possible return values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// OLE_E_BLANK + /// An appropriate cache is not available. + /// + /// + /// + /// + /// The OLE-provided implementation of IViewObject2::GetExtent searches the cache for the size of the view object. + /// The IOleObject::GetExtent method in the IOleObject interface provides some of the same information as IViewObject2::GetExtent. + /// + /// This method must return the same size as DVASPECT_CONTENT for all the new aspects in DVASPECT2. IOleObject::GetExtent must + /// do the same thing. + /// + /// + /// If one of the new aspects is requested in dwAspect, this method can either fail or return the same rectangle as for the + /// DVASPECT_CONTENT aspect. + /// + /// Notes to Callers + /// + /// To prevent the object from being run if it isn't already running, you can call IViewObject2::GetExtent rather than + /// IOleObject::GetExtent to determine the size of the presentation to be drawn. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/nf-oleidl-iviewobject2-getextent HRESULT GetExtent( DWORD + // dwDrawAspect, LONG lindex, DVTARGETDEVICE *ptd, LPSIZEL lpsizel ); + HRESULT GetExtent(uint dwDrawAspect, int lindex, in DVTARGETDEVICE ptd, out SIZE lpsizel); + } + + /// + /// Contains information about the accelerators supported by a container during an in-place session. The structure is used in the + /// IOleInPlaceSite::GetWindowContext method and the OleTranslateAccelerator function. + /// + /// + /// When an object is being in-place activated, its server calls the container's IOleInPlaceSite::GetWindowContext method, which + /// fills in an OLEINPLACEFRAMEINFO structure. During an in-place session, the message loop of an EXE server passes a pointer + /// to the OLEINPLACEFRAMEINFO structure to OleTranslateAccelerator. OLE uses the information in this structure to determine + /// whether a message maps to one of the container's accelerators. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/ns-oleidl-oleinplaceframeinfo typedef struct tagOIFI { UINT cb; BOOL + // fMDIApp; HWND hwndFrame; HACCEL haccel; UINT cAccelEntries; } OLEINPLACEFRAMEINFO, *LPOLEINPLACEFRAMEINFO; + [PInvokeData("oleidl.h", MSDNShortId = "e09445d2-61e5-4691-b51e-746e0cc91c00")] + [StructLayout(LayoutKind.Sequential)] + public struct OLEINPLACEFRAMEINFO + { + /// + /// The size of this structure, in bytes. The object server must specify sizeof( OLEINPLACEFRAMEINFO) in the structure it + /// passes to IOleInPlaceSite::GetWindowContext. The container can then use this size to determine the structure's version. + /// + public uint cb; + + /// Indicates whether the container is an MDI application. + [MarshalAs(UnmanagedType.Bool)] + public bool fMDIApp; + + /// A handle to the container's top-level frame window. + public HWND hwndFrame; + + /// A handle to the accelerator table that the container wants to use during an in-place editing session. + public HACCEL haccel; + + /// The number of accelerators in haccel. + public uint cAccelEntries; + } + + /// + /// Indicates the number of menu items in each of the six menu groups of a menu shared between a container and an object server + /// during an in-place editing session. This is the mechanism for building a shared menu. + /// + [PInvokeData("Oleidl.h", MSDNShortId = "ms693766")] + [StructLayout(LayoutKind.Sequential)] + public struct OLEMENUGROUPWIDTHS + { + /// + /// An array whose elements contain the number of menu items in each of the six menu groups of a shared in-place editing menu. + /// Each menu group can have any number of menu items. The container uses elements 0, 2, and 4 to indicate the number of menu + /// items in its File, View, and Window menu groups. The object server uses elements 1, 3, and 5 to indicate the number of menu + /// items in its Edit, Object, and Help menu groups. + /// + [MarshalAs(UnmanagedType.ByValArray, SizeConst = 6)] + public uint[] width; + } + + /// + /// Defines a verb that an object supports. The IOleObject::EnumVerbs method creates an enumerator that can enumerate these + /// structures for an object, and supplies a pointer to the enumerator's IEnumOLEVERB. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/oleidl/ns-oleidl-oleverb typedef struct tagOLEVERB { LONG lVerb; LPOLESTR + // lpszVerbName; DWORD fuFlags; DWORD grfAttribs; } OLEVERB, *LPOLEVERB; + [PInvokeData("oleidl.h", MSDNShortId = "657e3cc3-67fb-4458-8dad-f2a31df1b631")] + [StructLayout(LayoutKind.Sequential)] + public struct OLEVERB + { + /// Integer identifier associated with this verb. + public int lVerb; + + /// Pointer to a string that contains the verb's name. + [MarshalAs(UnmanagedType.LPWStr)] + public string lpszVerbName; + + /// + /// In Windows, a group of flags taken from the flag constants beginning with MF_ defined in AppendMenu. Containers should use + /// these flags in building an object's verb menu. All Flags defined in AppendMenu are supported except for MF_BITMAP, + /// MF_OWNERDRAW, and MF_POPUP. + /// + public uint fuFlags; + + /// Combination of the verb attributes in the OLEVERBATTRIB enumeration. + public OLEVERBATTRIB grfAttribs; } } \ No newline at end of file diff --git a/PInvoke/Shared/WinGdi/WinGdi.LOGPALETTE.cs b/PInvoke/Shared/WinGdi/WinGdi.LOGPALETTE.cs index 2e23c29a..6d6cee47 100644 --- a/PInvoke/Shared/WinGdi/WinGdi.LOGPALETTE.cs +++ b/PInvoke/Shared/WinGdi/WinGdi.LOGPALETTE.cs @@ -1,97 +1,91 @@ -using System; +#nullable enable +using System; using System.Runtime.InteropServices; using Vanara.Extensions; +using Vanara.InteropServices; -namespace Vanara.PInvoke +namespace Vanara.PInvoke; + +/// The alpha intensity value for the palette entry. +[PInvokeData("wingdi.h")] +[Flags] +public enum PC : byte { - /// The alpha intensity value for the palette entry. - [PInvokeData("wingdi.h")] - [Flags] - public enum PC : byte - { - /// - /// Specifies that the low-order word of the logical palette entry designates a hardware palette index. This flag allows the - /// application to show the contents of the display device palette. - /// - PC_EXPLICIT = 0x2, + /// + /// Specifies that the low-order word of the logical palette entry designates a hardware palette index. This flag allows the + /// application to show the contents of the display device palette. + /// + PC_EXPLICIT = 0x2, - /// - /// Specifies that the color be placed in an unused entry in the system palette instead of being matched to an existing color in - /// the system palette. If there are no unused entries in the system palette, the color is matched normally. Once this color is - /// in the system palette, colors in other logical palettes can be matched to this color. - /// - PC_NOCOLLAPSE = 0x4, + /// + /// Specifies that the color be placed in an unused entry in the system palette instead of being matched to an existing color in + /// the system palette. If there are no unused entries in the system palette, the color is matched normally. Once this color is + /// in the system palette, colors in other logical palettes can be matched to this color. + /// + PC_NOCOLLAPSE = 0x4, - /// - /// Specifies that the logical palette entry be used for palette animation. This flag prevents other windows from matching colors - /// to the palette entry since the color frequently changes. If an unused system-palette entry is available, the color is placed - /// in that entry. Otherwise, the color is not available for animation. - /// - PC_RESERVED = 0x1, - } + /// + /// Specifies that the logical palette entry be used for palette animation. This flag prevents other windows from matching colors + /// to the palette entry since the color frequently changes. If an unused system-palette entry is available, the color is placed + /// in that entry. Otherwise, the color is not available for animation. + /// + PC_RESERVED = 0x1, +} - /// The LOGPALETTE structure defines a logical palette. - /// - /// The colors in the palette-entry table should appear in order of importance because entries earlier in the logical palette are - /// most likely to be placed in the system palette. - /// - // https://docs.microsoft.com/en-us/windows/desktop/api/wingdi/ns-wingdi-taglogpalette typedef struct tagLOGPALETTE { WORD - // palVersion; WORD palNumEntries; PALETTEENTRY palPalEntry[1]; } LOGPALETTE, *PLOGPALETTE, *NPLOGPALETTE, *LPLOGPALETTE; - [PInvokeData("wingdi.h", MSDNShortId = "99d70a0e-ac61-4a88-a500-66443e7882ad")] - [StructLayout(LayoutKind.Sequential)] - public class LOGPALETTE : IDisposable - { - /// The version number of the system. - public ushort palVersion; +/// The LOGPALETTE structure defines a logical palette. +/// +/// The colors in the palette-entry table should appear in order of importance because entries earlier in the logical palette are +/// most likely to be placed in the system palette. +/// +// https://docs.microsoft.com/en-us/windows/desktop/api/wingdi/ns-wingdi-taglogpalette typedef struct tagLOGPALETTE { WORD +// palVersion; WORD palNumEntries; PALETTEENTRY palPalEntry[1]; } LOGPALETTE, *PLOGPALETTE, *NPLOGPALETTE, *LPLOGPALETTE; +[PInvokeData("wingdi.h", MSDNShortId = "99d70a0e-ac61-4a88-a500-66443e7882ad")] +[VanaraMarshaler(typeof(SafeAnysizeStructMarshaler), nameof(palNumEntries))] +[StructLayout(LayoutKind.Sequential)] +public class LOGPALETTE +{ + /// The version number of the system. + public ushort palVersion; - /// The number of entries in the logical palette. - public ushort palNumEntries; + /// The number of entries in the logical palette. + public ushort palNumEntries; - private IntPtr _palPalEntry; + /// Specifies an array of PALETTEENTRY structures that define the color and usage of each entry in the logical palette. + [MarshalAs(UnmanagedType.ByValArray, SizeConst = 1)] + public PALETTEENTRY[]? palPalEntry; +} - /// Specifies an array of PALETTEENTRY structures that define the color and usage of each entry in the logical palette. - public PALETTEENTRY[] palPalEntry - { - get => _palPalEntry.ToArray(palNumEntries); - set { Marshal.FreeHGlobal(_palPalEntry); value.MarshalToPtr(Marshal.AllocHGlobal, out _); } - } +/// Specifies the color and usage of an entry in a logical palette. +// https://docs.microsoft.com/en-us/windows/desktop/api/wingdi/ns-wingdi-tagpaletteentry typedef struct tagPALETTEENTRY { BYTE peRed; +// BYTE peGreen; BYTE peBlue; BYTE peFlags; } PALETTEENTRY, *PPALETTEENTRY, *LPPALETTEENTRY; +[PInvokeData("wingdi.h")] +[StructLayout(LayoutKind.Sequential)] +public struct PALETTEENTRY +{ + /// + /// Type: BYTE + /// The red intensity value for the palette entry. + /// + public byte peRed; - /// Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources. - void IDisposable.Dispose() => Marshal.FreeHGlobal(_palPalEntry); - } + /// + /// Type: BYTE + /// The green intensity value for the palette entry. + /// + public byte peGreen; - /// Specifies the color and usage of an entry in a logical palette. - // https://docs.microsoft.com/en-us/windows/desktop/api/wingdi/ns-wingdi-tagpaletteentry typedef struct tagPALETTEENTRY { BYTE peRed; - // BYTE peGreen; BYTE peBlue; BYTE peFlags; } PALETTEENTRY, *PPALETTEENTRY, *LPPALETTEENTRY; - [PInvokeData("wingdi.h")] - [StructLayout(LayoutKind.Sequential)] - public struct PALETTEENTRY - { - /// - /// Type: BYTE - /// The red intensity value for the palette entry. - /// - public byte peRed; + /// + /// Type: BYTE + /// The blue intensity value for the palette entry. + /// + public byte peBlue; - /// - /// Type: BYTE - /// The green intensity value for the palette entry. - /// - public byte peGreen; - - /// - /// Type: BYTE - /// The blue intensity value for the palette entry. - /// - public byte peBlue; - - /// - /// Type: BYTE - /// - /// The alpha intensity value for the palette entry. Note that as of DirectX 8, this member is treated differently than - /// documented for Windows. - /// - /// - public PC peFlags; - } + /// + /// Type: BYTE + /// + /// The alpha intensity value for the palette entry. Note that as of DirectX 8, this member is treated differently than + /// documented for Windows. + /// + /// + public PC peFlags; } \ No newline at end of file diff --git a/UnitTests/PInvoke/Gdi32/Gdi32Tests.cs b/UnitTests/PInvoke/Gdi32/Gdi32Tests.cs index 560e0c38..e7c27341 100644 --- a/UnitTests/PInvoke/Gdi32/Gdi32Tests.cs +++ b/UnitTests/PInvoke/Gdi32/Gdi32Tests.cs @@ -34,6 +34,14 @@ namespace Vanara.PInvoke.Tests Assert.That(CreateFont(), ResultIs.ValidHandle); } + [Test] + public void CreatePaletteTest() + { + LOGPALETTE lp = new() { palVersion = 0x300, palNumEntries = 32, palPalEntry = new PALETTEENTRY[32] }; + for (int i = 0;i < 32; i++) { lp.palPalEntry[i] = new() { peFlags = PC.PC_NOCOLLAPSE }; } + Assert.That(CreatePalette(lp), ResultIs.ValidHandle); + } + // TODO: [Test] public void DeleteDCTest() {