System.Private.Windows.Core The standard Microsoft public library public key. The token is b03f5f7f11d50a3a. The standard Microsoft shared library public key. The token is 31bf3856ad364e35. The standard Microsoft ECMA key. The token is b77a5c561934e089. The open key. The token is cc7b13ffcd2ddd51. The standard Moq (mocking test library) public key. The full name of the mscorlib assembly on .NET Framework 4.x. The full name of the System.Drawing assembly on .NET Framework 4.x. The full name of the System.Drawing.Design assembly on .NET Framework 4.x. The full name of the System.Windows.Forms assembly on .NET Framework 4.x. The full name of the System.Design assembly on .NET Framework 4.x. Allows renting a buffer from with a using statement. Can be used directly as if it were a . Buffers are not cleared and as such their initial contents will be random. Create the with an initial buffer. Useful for creating with an initial stack allocated buffer. Create the with an initial buffer. Useful for creating with an initial stack allocated buffer. Creating with a stack allocated buffer: using BufferScope<char> buffer = new(stackalloc char[64]); Stack allocated buffers should be kept small to avoid overflowing the stack. The required minimum length. If the is not large enough, this will rent from the shared . Ensure that the buffer has enough space for number of elements. Consider if creating new instances is possible and cleaner than using this method. True to copy the existing elements when new space is allocated. Array based collection that tries to avoid copying the internal array and caps the maximum capacity. To mitigate corrupted length attacks, the backing array has an initial allocation size cap. The cannot grow past this value and is expected to be this value when the collection is "finished". Creates a list trimmed to the given count. This is an optimized implementation that avoids iterating over the entire list when possible. Helper class for converting values. It is intended to save the allocation of a temporary list when converting values. If there are multiple passes through the list this class should usually be avoided. Base class for implementing with double disposal protection. Called when the component is being disposed or finalized. if called via a destructor on the finalizer queue. Do not access object fields unless . Disposes the component. with a finalizer. Used to suppress finalization in debug builds only. Unfortunately this can only be used when there is a single implicit conversion operator when called from a ref struct. C# tries to cast to anything that fits in object, which leads to an ambiguous error. You need to add GC.SuppressFinalize under #ifdef when you don't have a single implicit conversion. Returns if the exception is an exception that isn't recoverable and/or a likely bug in our implementation. Converts the given exception to a if needed, nesting the original exception and assigning the original stack trace. Reads a binary formatted from the given . The data was invalid. Creates a object from raw data with validation. was invalid. Returns the remaining amount of bytes in the given . Reads an array of primitives. Writes a collection of primitives. Only supports , , , , , , , , , , , , , , and . Writes a object to the given . Writes . Simple run length encoder (RLE) that works on spans. Format used is a byte for the count, followed by a byte for the value. Get the encoded length, in bytes, of the given data. Get the decoded length, in bytes, of the given encoded data. Encode the given data into the given span. if the span was not large enough to hold the encoded data. Get a wrapper around the given . Use the return value in a scope. Save the contents of the to a new . The stream to save to the . The memory handle if successful. If a non null value is passed in, it will be freed. if successful. Dereferences records. Writer that writes specific types in binary format without using the BinaryFormatter. Writes a in binary format. Writes a in binary format. Writes a in binary format. Writes a in binary format. Writes a nint in binary format. Writes a nuint in binary format. Writes a in binary format. Writes a in binary format. Writes a in binary format. Writes a in binary format. Writes a in binary format. Writes a in binary format. Writes a in binary format. Attempts to write a value in binary format. if successful. Writes a .NET primitive value in binary format. is not a a primitive value. Writes a in binary format. Writes a primitive list in binary format. Writes the given in binary format if supported. Writes the given in binary format if supported. Writes the given in binary format if supported. Tries to write the given if supported. Writes a of primitive to primitive values to the given stream in binary format. Primitive types are anything in the enum. contained non-primitive values or a custom comparer or hash code provider. Writes a in binary format. Writes the given if supported. Writes the given to stream, only types that have TypeConverters are supported. This function is needed for the Clipboard serialization as Clipboard is not using TypeConverters. Simple wrapper to ensure the is reset to its original position if the throws. Simple wrapper to ensure the is reset to its original position if the throws or returns . Base class for deserializing s. Deserializer for s that directly set fields. Deserializer for s that use to initialize class state. This is used either because the class implements or because a surrogate was used. How exactly assembly names need to match for deserialization. Aligned with FormatterAssemblyStyle behavior. Type name binder. Optional type provider. Streaming context. General binary format deserializer. This has some constraints over the BinaryFormatter. Notably it does not support all usages or surrogates that replace object instances. This greatly simplifies the deserialization. It also does not allow offset arrays (arrays that have lower bounds other than zero) or multidimensional arrays that have more than elements. This deserializer ensures that all value types are assigned to fields or populated in callbacks with their final state, throwing if that is impossible to attain due to graph cycles or data corruption. The value type instance may contain references to uncompleted reference types when there are cycles in the graph. In general it is risky to dereference reference types in constructors or in call backs if there is any risk of the objects enabling a cycle. If you need to dereference reference types in waiting for final state by implementing or is the safer way to do so. This deserializer does not fire completed events until the entire graph has been deserialized. If a surrogate () needs to dereference with potential cycles it would require tracking instances by stashing them in a provided to handle after invoking the deserializer. makes deserializing difficult as you don't know the final type until you've finished populating the serialized type. If is involved and you have a cycle you may never be able to complete the deserialization as the reference type values in the can't get the final object. is really the only practical way to represent singletons. A common pattern is to nest an object in an object. Specifying the nested type when is called by invoking will get that type info serialized into the stream. Deserializes the object graph for the given and . Interface for deserialization used to define the coupling between the main and its s. The current deserialization options. The set of object record ids that are not considered "complete" yet. Objects are considered incomplete if they contain references to value or types that need completed or if they have not yet finished evaluating all of their member data. They are also considered incomplete if they implement or have a surrogate and the has not yet been applied. The set of objects that have been deserialized, indexed by record id. Objects may not be fully filled out. If they are not in , they are guaranteed to have their reference type members created (this is not transitive- their members may not be ready if there are cycles in the object graph). Resolver for types. Pend the given value updater to be run when it's value type dependency is complete. Pend a to be applied when the graph is fully parsed. Mark the object id as complete. This will check dependencies and resolve relevant s. Check for a surrogate for the given type. If none exists, returns . Continue parsing. The id that is necessary to complete parsing or default value if complete. Gets the actual object for a member value primitive or record. Returns if the object record has not been encountered yet. Called for new non-primitive reference types. Returns if the given record's value needs an updater applied. The value id that needs to be reapplied. The object id that is dependent on . Resolver for types. Resolves the given type name against the specified library. Throws if the type cannot be resolved. Tries to resolve the given type name against the specified library. Add all methods to a delegate. Array information structure. [MS-NRBF] 2.4.2.1 Base class for array records. [MS-NRBF] 2.4 describes how item records must follow the array record and how multiple null records can be coalesced into an or record. Identifier for the array. Length of the array. Typed class for array records. The array items. Multi-null records are always expanded to individual entries when reading. Returns the item at the given index. Single dimensional array of objects. [MS-NRBF] 2.4.3.2 Single dimensional array of a primitive type. [MS-NRBF] 2.4.3.3 Single dimensional array of strings. [MS-NRBF] 2.4.3.4 Library full name information. [MS-NRBF] 2.6.2 String record. [MS-NRBF] 2.5.7 Identifies the remoting type of a class member or array item. [MS-NRBF] 2.1.2.2 Type is defined by and it is not a string. Type is length prefixed string. Type is System.Object. Type is a standard .NET object. Type is an object. Type is a single-dimensional array of objects. Type is a single-dimensional array of strings. Types is a single-dimensional array of a primitive type. Class info. [MS-NRBF] 2.3.1.1 Base class for class records. Includes the values for the class (which trail the record) [MS-NRBF] 2.3. Writes as specified by the Identifies a class by it's name and library id. [MS-NRBF] 2.1.1.8 Class information that references another class record's metadata. [MS-NRBF] 2.3.2.5 The ObjectId of a prior or . Class information with type info and the source library. [MS-NRBF] 2.3.2.1 Expresses that the object can be written with a Writes the current object to the given . Record that represents a primitive type or an array of primitive types. Map of records. Non-generic record base interface. Id for the record, or null if the record has no id. Typed record interface. Expresses that the object can be written with a Writes the current object to the given . Primitive value other than . [MS-NRBF] 2.5.1 is not primitive. The record contains a reference to another record that contains the actual value. [MS-NRBF] 2.5.3 Member type info. [MS-NRBF] 2.3.1.2 Record that marks the end of the binary format stream. Base class for null records. Multiple null object record. [MS-NRBF] 2.5.5 Multiple null object record (less than 256). [MS-NRBF] 2.5.5 Null object record. [MS-NRBF] 2.5.4 Primitive type. [MS-NRBF] 2.1.2.3 Base record class. Writes as to the given . Writes records, coalescing null records into single entries. contained an object that isn't a record. Map of records that ensures that IDs are only entered once. Record type. [MS-NRBF] 2.1.2.1 Binary format header. [MS-NRBF] 2.6.1 The id of the root object record. Ignored. BinaryFormatter puts out -1. Must be 1. Must be 0. System class information with type info. [MS-NRBF] 2.3.2.3 that only returns default values. Allows creating a when a isn't necessary. Get a typed value. Hard casts. Helper to create and track records for and when duplicates are found. Returns the appropriate record for the given string. Returns the for the given . or if not a . If , then Clipboard and DataObject Get and Set methods will attempts to serialize or deserialize binary formatted content using either or System.Windows.Forms.BinaryFormat.Deserializer. To use , application should also opt in into the "System.Runtime.Serialization.EnableUnsafeBinaryFormatterSerialization" option and reference the out-of-band "System.Runtime.Serialization.Formatters" NuGet package and opt out from using the System.Windows.Forms.BinaryFormat.Deserializer by setting "Windows.ClipboardDragDrop.EnableNrbfSerialization" to If , then Clipboard Get methods will prefer System.Windows.Forms.BinaryFormat.Deserializer to deserialize the payload, if needed. If , then is used to get full compatibility with the downlevel versions of .NET. This switch has no effect if "Windows.ClipboardDragDrop.EnableUnsafeBinaryFormatterSerialization" is set to . If , then async capable drag/drop operations will not be performed in a synchronous manner. Some drag sources only support async operations. Notably, Chromium-based applications with file drop (the new Outlook is one example). To enable applications to accept filenames from these sources we use the interface when available and just do the operation synchronously. This isn't expected to be a problem, but if it is we'll provide a way to opt out of this behavior. The flag may also be useful for testing purposes. Positive enforcing count of items. Idea here is that doing this makes it less likely we'll slip through cases where we don't check for negative numbers. And also not confuse counts with ids. Feature switch that wraps whether or not is enabled. By wrapping in a feature switch, the setting can be used to control trim warnings related to usage of the . Code past a feature switch isn't considered for warnings if the switch isn't enabled. Platform agnostic interface for a bitmap. Gets a Win32 HBITMAP handle for this bitmap. Size of the bitmap in pixels. Identifier struct. Wrapper which contains JSON serialized data along with the JSON data's original type information to be deserialized later. There may be instances where this type is not available in different versions, e.g. .NET 8, .NET Framework. If this type needs to be deserialized from stream in these instances, a workaround would be to create an assembly with the name and replicate this type. Then, manually retrieve the serialized stream and use the to decode the stream and rehydrate the serialized type. Alternatively, but not recommended, BinaryFormatter can also be used to deserialize the stream if this type is not available. k__BackingField") is not System.Formats.Nrbf.SZArrayRecord byteData || types.GetRawValue("k__BackingField") is not string innerTypeAssemblyQualifiedName || !System.Reflection.Metadata.TypeName.TryParse(innerTypeAssemblyQualifiedName.ToCharArray(), out System.Reflection.Metadata.TypeName? innerTypeName)) { // This is supposed to be JsonData, but somehow the data is corrupt. throw new InvalidOperationException(); } // TODO: Additional checking on 'innerTypeName' to ensure it is expected type. // This should return the original data that was JSON serialized. var result = System.Text.Json.JsonSerializer.Deserialize(byteData.GetArray(), innerType); // TODO: Process the payload as needed. } [DllImport("kernel32.dll")] static extern int GlobalSize(IntPtr hMem); [DllImport("kernel32.dll")] static extern IntPtr GlobalLock(IntPtr hMem); [DllImport("kernel32.dll")] static extern int GlobalUnlock(IntPtr hMem); // OR // Not recommended: deserialize using BinaryFormatter. // This definition must live in an assembly named System.Private.Windows.VirtualJson and referenced in order to work as expected. namespace System.Private.Windows; [Serializable] struct JsonData : IObjectReference { public byte[] JsonBytes { get; set; } public string InnerTypeAssemblyQualifiedName { get; set; } public object GetRealObject(StreamingContext context) { // TODO: Additional checking on InnerTypeAssemblyQualifiedName to ensure it is expected type. return JsonSerializer.Deserialize(JsonBytes, typeof(ExpectedType)) ?? throw new InvalidOperationException(); } } ]]> Represents an object that contains JSON serialized data. This interface is used to identify a without needing to have the generic type information. The assembly qualified name of the T in . This name should have any names taken into account. Deserializes the data stored in the JsonData. This is a convenience method to deserialize the data when we are not dealing with a binary formatted record. Core NRBF serializer. Supports common .NET types. Represents a fully qualified type name split into assembly name and type name. Tries to write supported objects to a stream. Tries to read supported objects from a . Tries to bind the given type name to a supported type. Returns if the type is fully supported by the serializer. This should only return for types that are expected to be safe to deserialize. It is used to indicate that we should consider the type "corrupted" and should not make a second attempt through the . It is also used as the allowed list of types that we'll auto-bind when user type resolvers return . and can handle some types partially. All types should be vetted to ensure that they are resilient to corrupted primitive data in the BinaryFormatter deserialization process. There can be no possibility of cycles (direct or indirect self-reference) or ways to break object state with bad primitive data (invalid enum values, etc.). If the type has a serialization constructor, it must be safe to call with any data. If the type does not have a serialization constructor, it must be safe to populate all instance fields with any data. Accepted types should not be abstract and should be sealed. We make no guarantees here about the safety of using the BinaryFormatter with these types. This is a best effort to help avoid corruption exploitation. Hashtable is one that we return false for, for example. While we handle ones that have nothing beyond primitives (such as `string` to `string`), we don't support anything else, including custom comparers. Decodes a NRBF stream, converting any exceptions to . Deserializes the to an object. Tries to get this object as a . Tries to get this object as a . Tries to get this object as a . Tries to get this object as a . Tries to get this object as a . Tries to get this object as a . Tries to get this object as a . Tries to get this object as a primitive type or string. if this represented a primitive type or string. Tries to get this object as a of . Tries to get this object as a of values. Tries to get this object as an of primitive types. Tries to get this object as a binary formatted of keys and values. Tries to get this object as a binary formatted of keys and values. Tries to get this object as a binary formatted . Try to get a supported .NET type object (not WinForms) that has no . Try to get a supported System.Drawing.Primitives object that has a . This method is used for Clipboard payload deserialization. ResX deserialization uses s for these types. Tries to deserialize this object if it was serialized as JSON. When is returned, this will be the deserialized object or if is was a JSON serialized type and the type did not match. If the data was supposed to be our , but was serialized incorrectly. If an exception occurred while JSON deserializing. We don't try to resolve all types in the graph of a type when deserializing JSON as the default options should not present the same risks as BinaryFormatter deserialization. JSON binding is just for the root type. Writes an object to the provided memory stream. The memory stream to write the object to. The object to write to the stream. The format of the data being written. Thrown when is not supported. Reads an object from the provided memory stream. The type of the object to read. The memory stream to read the object from. The data request containing the format and resolver. The deserialized object, or if the data is not of the given type. Thrown when is not enabled. Contains platform-agnostic clipboard operations. The number of times to retry OLE clipboard operations. The amount of time in milliseconds to sleep between retrying OLE clipboard operations. Removes all data from the Clipboard. An indicating the success or failure of the operation. Flushes data to the Clipboard. An indicating the success or failure of the operation. Attempts to set the specified data on the Clipboard. The data object to set on the Clipboard. Indicates whether to copy the data to the Clipboard. The number of times to retry the operation if it fails. The amount of time in milliseconds to wait between retries. An indicating the success or failure of the operation. Attempts to retrieve data from the Clipboard. The proxy data object retrieved from the Clipboard. The original object retrieved from the Clipboard, if available. An indicating the success or failure of the operation. Returns true if the given is currently on the Clipboard. This is meant to emulate the OleIsCurrentClipboard API. The object to check. 'true' if is currently on the Clipboard. Returns the data that is currently on the clipboard as the platform specified . Checks if the specified is valid and compatible with the specified . This is intended to be used as a pre-validation step to give a more useful error to callers. Contains the logic to move between , , and calls. Stores the data in the specified format using the . The format associated with the data. See DataFormats for predefined formats. The data to store. The default behavior of is used to serialize the data. See and for more details on default behavior. If custom JSON serialization behavior is needed, manually JSON serialize the data and then use SetData, or create a custom , attach the , and then recall this method. See for more details on custom converters for JSON serialization. Maps to . Returns true if the tymed is usable. Maps native pointer to . Retrieves the specified format from the specified . Extracts a managed object from of the specified format. A restricted type was encountered, do not continue trying to deserialize. if the managed object of was successfully created, if the payload does not contain the specified format or the specified type. If contains that contains a serialized object, we return that object cast to or null. If that is not a serialized object, and a stream was requested, i.e. can be assigned to we return that . is deserialization failed. Maps native pointer to the .NET Runtime . Maps the runtime to the native . A format used internally by the drag image manager. A format that contains the drag image bottom-up device-independent bitmap bits. A format that contains the value passed to and controls whether to allow text specified in to be displayed on the drag image. A format used to identify an object's drag image window so that it's visual information can be updated dynamically. A format that is non-zero if the drop target supports drag images. A format that is non-zero if the drop target supports drop description text. A format that is non-zero if the drag image is a layered window with a size of 96x96. Adds all the "synonyms" for the specified format. Check if the is one of the predefined formats, which formats that correspond to primitives or are pre-defined in the OS such as strings, bitmaps, and OLE types. Ensures that the Win32 predefined formats are setup in our format list. This is called anytime we need to search the list JSON serialize the data only if the format is not a restricted deserialization format and the data is not an intrinsic type. or is null. is empty, whitespace, or a predefined format -or- isa a DataObject. Encapsulates state of a data request. Provides the list of custom allowed types that user considers safe to deserialize from the payload. Resolver should recognize the closure of all non-primitive and not known types in the payload, such as field types and types in the inheritance hierarchy and the code to match these types to the s read from the deserialized stream. if the user had not requested any specific type, i.e. the call originates from API family, that returns an . if the user had requested a specific type by calling API family. This is the only method that has special behavior for objects. Represents a private format used for data transfer by the drag-and-drop helpers. Initializes a new instance of the class using the specified format, storage medium, and owner. Returns a copy of the storage medium in this instance. Refreshes the storage medium in this instance. Copies a given storage medium. A copy of . Frees the storage medium in this instance. Helper class for drop targets to display the drag image while the cursor is over the target window and allows the application to specify the drag image bitmap that will be displayed during a drag-and-drop operation. This class effectively requires the data object on events to be an instance of DataObject (via ) currently. Sets the drop object image and accompanying text back to the default. Notifies the drag-image manager that the drop target has been entered, and provides it with the information needed to display the drag image. Notifies the drag-image manager that the drop target has been entered, and provides it with the information needed to display the drag image. Notifies the drag-image manager that the cursor has left the drop target. Notifies the drag-image manager that the cursor position has changed and provides it with the information needed to display the drag image. Notifies the drag-image manager that the object has been dropped, and provides it with the information needed to display the drag image. Determines whether the data object is in a drag loop. if is in a drag-and-drop loop; otherwise . Determines whether the specified format is a drag loop format. if is a drag loop format; otherwise . Releases formats used by the drag-and-drop helper. Sets boolean formats into a data object used to set and display drag images and drop descriptions. Initializes the drag-image manager and sets the drag image bitmap into a data object. Because InitializeFromBitmap always performs the RGB multiplication step in calculating the alpha value, you should always pass a bitmap without pre-multiplied alpha blending. Note that no error will result from passing a bitmap with pre-multiplied alpha blending, but this method will multiply it again, doubling the resulting alpha value. Initializes the drag-image manager and sets the drag image bitmap into a data object. Because InitializeFromBitmap always performs the RGB multiplication step in calculating the alpha value, you should always pass a bitmap without pre-multiplied alpha blending. Note that no error will result from passing a bitmap with pre-multiplied alpha blending, but this method will multiply it again, doubling the resulting alpha value. Sets the drop description into a data object. Describes the image and accompanying text for a drop object. Sets the drop description into a data object. Describes the image and accompanying text for a drop object. Some UI coloring is applied to the text in if used by specifying %1 in . The characters %% and %1 are the subset of FormatMessage markers that are processed here. Sets the InDragLoop format into a data object. Used to determine whether the data object is in a drag loop. Sets the IsShowingText format into a data object. To effectively display the drop description after changing the drag image bitmap, set to true; otherwise the drop description text will not be displayed. Sets the UsingDefaultDragImage format into a data object. Specify for to use a layered window drag image with a size of 96x96. Creates an in-process server drag-image manager object and returns the specified interface pointer. Part of IComDataObject, used to interop with OLE. Used to filter to fully COM visible data objects. Notably the platform specific DataObject class. Internal interface for a data format. Specifies the name of this format. Specifies the ID number for this format. Typed interface for a data format that allows for creation. Creates a new instance of the data format. Internal interface for a data object class. The methods here abstract the platform specific IDataObject and ITypedDataObject interfaces in both WPF and WinForms. It composes the two interfaces. Retrieves the data associated with the specified data format, using to determine whether to convert the data to the format. Retrieves the data associated with the specified data format. Retrieves the data associated with the specified class type format. Determines whether data stored in this instance is associated with the specified format, using to determine whether to convert the data to the format. Determines whether data stored in this instance is associated with, or can be converted to, the specified format. Determines whether data stored in this instance is associated with, or can be converted to, the specified format. Gets a list of all formats that data stored in this instance is associated with or can be converted to, using to determine whether to retrieve all formats that the data can be converted to, or only native data formats. Gets a list of all formats that data stored in this instance is associated with or can be converted to. Stores the specified data and its associated format in this instance, using autoConvert to specify whether the data can be converted to another format. Stores the specified data and its associated format in this instance. Stores the specified data and its associated class type in this instance. Stores the specified data in this instance, using the class of the data for the format. Retrieves data associated with data format named after , if that data is of type . Retrieves data associated with the specified format if that data is of type . Retrieves data in a specified format if that data is of type , optionally converting the data to the specified format. Retrieves typed data associated with the specified data format. A user-provided function that maps to . A string that specifies what format to retrieve the data as. See the DataFormats class for a set of predefined data formats. to attempt to automatically convert the data to the specified format; for no data format conversion. A data object with the data in the specified format, or if the data is not available in the specified format or is of a wrong type. if the data of this format is present and the value is of a matching type and that value can be successfully retrieved. The should throw for types it does not want loaded. The consuming method should honor this and not load the requested type. The resolver can also return to indicate that it wants default handling, which may also result in a resolution failure. Platform typed data object interface. Provides methods to construct and unwrap platform specific data objects. Unwraps the user IDataObject instance when applicable. This is used to return the "original" IDataObject instance when getting data back from OLE. Providing the original instance back allows casting to the original type, which historically happened through "magic" casting support for built-in COM interop. Now that we use ComWrappers, we can't rely on the "magic" casting support. Instead, we provide the original object back when we're able to unwrap it. The unfortunate caveat is that the behavior of calling through the OLE IDataObject proxy results in different behavior than calling through the original object. This primarily happens through `autoConvert` scenarios, where no such concept exists in the COM interfaces. As such, when calling through the COM interface, "autoConvert" is always considered to be . To mitigate the COM caveat, we do not give back the original DataObject if we created it implicitly via Clipboard.SetData. This allows the calls to go through the proxy, which gets the expected "autoConvert" behavior. One potential alternative would be to wrap the created IDataObject in an adapter that mimics the "autoConvert" behavior. This would avoid BinaryFormat serialization when in process and not copying. true when a data object was returned. Gets the x-coordinate of the mouse pointer. Gets the y-coordinate of the mouse pointer. Gets which drag-and-drop operations are allowed by the target of the drag event. Gets the drop description image type. Data object, if any, associated with the drag event. Gets or sets the drop description text such as "Move to %1". UI coloring is applied to the text in if used by specifying %1 in . Gets or sets the drop description text such as "Documents" when %1 is specified in . UI coloring is applied to the text in if used by specifying %1 in . Runtime agnostic interface for the GiveFeedback event. Gets the drag image bitmap. Gets the drag image cursor offset. Gets a value indicating whether a layered window drag image is used. Platform specific OLE services. This method is called to validate that OLE is initialized and that the current thread is a single-threaded apartment (STA). Current thread is not in the right state for OLE. Called after unsuccessfully performing clipboard serialization. and are checked for validity before this call. The data format that is being serialized. If the is a the requested format this method will attempt to extract it from the . The data format that is being requested. This is intended for platform specific logic, notably for bitmaps and metafiles. if a bitmap was extracted. Returns true if the given is a valid type for the given . Basic predefined formats that map to are checked before this call. Allows the given to pass pre-validation without a resolver. Allows custom validation or adapting of data and formats. The format to be checked against , can be modified to another format name if is true. The data to be checked against . Creates an instance. /> This exception is used to indicate that clipboard contains a serialized managed object that contains unexpected types and that we should stop processing this data. Specifies the standard ANSI text format. Specifies the standard Windows Unicode text format. Specifies text consisting of Rich Text Format (RTF) data. Specifies text consisting of HTML data. Specifies a comma-separated value (CSV) format, which is a common interchange format used by spreadsheets. Specifies a data format as Xaml. A type resolver for use when processing binary formatted streams. If the resolver function is not provided, a resolver is created that handles the specified root . If the resolver returns , the is used to attempt to bind the type. If the type is not fully supported, the type is not bound. If users want to override this behavior, they should throw in their resolver. Unbound types will throw a when attempting to bind. This class is used in and NRBF deserialization. Type resolver for use with and NRBF deserializers to restrict types that can be instantiated. that the user expects to read from the binary formatted stream. Simple scope for writing to HGLOBAL memory. Is Windows 10 first release or later. (Threshold 1, build 10240, version 1507) Is Windows 10 Anniversary Update or later. (Redstone 1, build 14393, version 1607) Is Windows 10 Creators Update or later. (Redstone 2, build 15063, version 1703) Is Windows 10 Creators Update or later. (Redstone 3, build 16299, version 1709) Is Windows 10 Creators Update or later. (Redstone 4, build 17134, version 1803) Is this Windows 11 public preview or later? The underlying API does not read supportedOs from the manifest, it returns the actual version. Is this Windows 11 version 22H2 or greater? The underlying API does not read supportedOs from the manifest, it returns the actual version. Is Windows 8.1 or later. Is Windows 8 or later. Unhandled VT: {0}. The constructor to deserialize an object of type '{0}' was not found. Surrogate must return the same object that was provided in the 'obj' parameter. IObjectReference type '{0}' can only have primitive member data. Objects could not be deserialized completely. Unexpected parser cycle. Could not find field '{0}' data for type '{1}'. Type '{0}' is not marked as serializable. Could not find type '{0}'. Clipboard format registration did not succeed. Failed to deserialize JSON data. External exception BinaryFormatter serialization and deserialization are disabled within this application. See https://aka.ms/binaryformatter for more information. BinaryFormatter is not supported in clipboard or drag-and-drop operations. BinaryFormatter is not supported in clipboard or drag-and-drop operations. Please enable it and use 'TryGetData<T>' APIs with a 'resolver' function that defines a set of allowed types to deserialize '{0}'. Please use 'TryGetData<T>' APIs with a 'resolver' function that defines a set of allowed types to deserialize '{0}'. Type {0} is not found. If this type is allowed, please ensure that the 'resolver' function provided in 'TryGetData<T>' APIs supports it. '{0}' is not a concrete type, and could result in an unbounded deserialization attempt. Please use a concrete type or alternatively define a 'resolver' function that supports types that you are expecting to retrieve from the clipboard or use in drag-and-dr ... The specified type '{0}' is not compatible with the specified format '{1}'. 'DataObject' can not be serialized as JSON directly. Use 'DataObject.SetDataAsJson' APIs to add JSON serialized data to an existing DataObject. Predefined formats should not be serialized as JSON. Clipboard contains a 'NotSupportedException' that indicates that write operation failed. '{0}'. Clipboard contains an unexpected type. The specified Clipboard format is not compatible with '{0}' type. Cannot operate with an empty collection. Path "{0}" in the argument "{1}" is not valid. Function was ended. File access is denied. File not found. A generic error occurred in GDI+. Buffer is too small (internal GDI+ error). Parameter is not valid. An object could not be created, possibly due to a lack of memory, but most likely due to invalid input. Not implemented. Overflow error. Property cannot be found. Property is not supported. Unknown GDI+ error occurred. Bitmap region is already locked. Image format is unknown. Current version of GDI+ does not support this feature. Font '{0}' cannot be found. Font '{0}' does not support style '{1}'. GDI+ is not properly initialized (internal GDI+ error). Object is currently in use elsewhere. Only TrueType fonts are supported. This is not a TrueType font. Compares s. Creates a comparer that does a fully qualified type name match. Creates a comparer that does a full type name match. Ignores the assembly. Creates a comparer that does a full type name and assembly name match. Ignores assembly version, culture, and public key token. Use the full name of the type (default). (Namespace + Name) Use the assembly name of the type. Use the assembly culture of the type. Use the assembly version of the type. Use the assembly public key token of the type. Use all parts of the fully qualified type name. Match all parts of the fully qualified type name except the assembly version. Copies the to the , terminating with null and truncating to fit if necessary. Slices the given at the first null found (if any). Slices the given at the first null found (if any). Fast stack based reader. Care must be used when reading struct values that depend on a specific field state for members to work correctly. For example, has a very specific set of valid values for its packed field. Inspired by patterns. Fast stack based reader. Care must be used when reading struct values that depend on a specific field state for members to work correctly. For example, has a very specific set of valid values for its packed field. Inspired by patterns. Try to read everything up to the given . Advances the reader past the if found. Try to read everything up to the given . The read data, if any. The delimiter to look for. to move past the if found. if the was found. Try to read the next value. Try to read a span of the given . Try to read a value of the given type. The size of the value must be evenly divisible by the size of . This is just a straight copy of bits. If has methods that depend on specific field value constraints this could be unsafe. The compiler will often optimize away the struct copy if you only read from the value. Try to read a span of values of the given type. The size of the value must be evenly divisible by the size of . This effectively does a and the same caveats apply about safety. Check to see if the given values are next. The span to compare the next items to. Advance the reader if the given values are next. The span to compare the next items to. if the values were found and the reader advanced. Advance the reader past consecutive instances of the given . How many positions the reader has been advanced Advance the reader by the given . Rewind the reader by the given . Reset the reader to the beginning of the span. Advance the reader without bounds checking. Slicing without bounds checking. Slicing without bounds checking. Fast stack based writer. Fast stack based writer. Try to write the given value. Try to write the given value. Try to write the given value times. Advance the writer by the given . Rewind the writer by the given . Reset the reader to the beginning of the span. String builder struct that allows using stack space for small strings. Get a pinnable reference to the builder. Does not ensure there is a null char after This overload is pattern matched in the C# 7.3+ compiler so you can omit the explicit method call, and write eg "fixed (char* c = builder)" Get a pinnable reference to the builder. Ensures that the builder has a null char after Returns the underlying storage of the builder. Returns a span around the contents of the builder. Ensures that the builder has a null char after Append a string to the builder. If the string is , this method does nothing. Name must be AppendLiteral to work with interpolated strings. Resize the internal buffer either by doubling current buffer size or by adding to whichever is greater. Number of chars requested beyond current position. Helper methods for comparing s and s. Match type against . The type to match. The type name to match against. Comparison options. Matches type name against . Matches the given type's assembly name against the given . A type to match assembly info against. Assembly name info to match against. Comparison options. if the assembly names meet the specified criteria. Matches the given assembly names against each other. The first assembly name to match. The second assembly name to match. Convert to . Take into account type forwarding in order to create compatible with the type names serialized to the binary format.This method removes nullability wrapper from the top level type only because in the serialization root record is not nullable, but the generic types could be nullable. If is a nullable type, return the underlying type; otherwise, return . Helper method that allows non-allocating conversion of a interpolated string to a . Compares two public keys by their token value. Handles comparing public key tokens to full public keys. This method allows efficient use of interpolated strings with A struct that can hold any value type or reference type without boxing primitive types or enums. Behavior matches casting to/from . Everything in this struct is designed to be as fast as possible. Changing logic should not be done without detailed performance measurements. Creates a new with the given . To avoid boxing enums, use the method instead. The of the value stored in this . Creates a new with the given value. This method can always be used and avoids boxing enums. Tries to get the value stored in this as the given type. Returns if the type matches. All types can be requested as . Primitive types can be requested as their own type or as a nullable of that type. Enums can be requested as their own type or a nullable of that type. Gets the value as the specified . The value is not of type . Allows packing some values into a single . that handles types that are a simple cast from a to a . A flag that represents the of a in a . Also provides the functionality to convert any to an that already isn't an . Converts the given to an . Strongly typed . Data union for the type. Data can be any blittable type, but should be 8 bytes or less to avoid growing the size of the type. Converts the to string and frees it. Converts the to a nullable string and frees it. Gets the length of the BSTR in characters. Never convert native constants (such as to or pass them through any conversion in , , etc. as they can change the value. is a DWORD- passing constants in native code would just pass the value as is. Read more on https://learn.microsoft.com. The COLORREF value is used to specify an RGB color. When specifying an explicit [RGB](/windows/desktop/api/Wingdi/nf-wingdi-rgb) color, the **COLORREF** value has the following hexadecimal form: `0x00bbggrr` The low-order byte contains a value for the relative intensity of red; the second byte contains a value for green; and the third byte contains a value for blue. The high-order byte must be zero. The maximum value for a single byte is 0xFF. To create a **COLORREF** color value, use the [RGB](/windows/desktop/api/Wingdi/nf-wingdi-rgb) macro. To extract the individual values for the red, green, and blue components of a color value, use the [**GetRValue**](/windows/desktop/api/Wingdi/nf-wingdi-getrvalue), [GetGValue](/windows/desktop/api/Wingdi/nf-wingdi-getgvalue), and [GetBValue](/windows/desktop/api/Wingdi/nf-wingdi-getbvalue) macros, respectively. Read more on docs.microsoft.com. The DECIMAL structure represents a decimal data type that provides a sign and scale for a number. Reserved. The high 32 bits of the number. Describes FILETIME and provides syntax, members, and additional remarks. A property of type PT_SYSTIME has a **FILETIME** structure for its value. Such a property has a **FILETIME** data type for the **Value** member in its definition in an [SPropValue](spropvalue.md) structure. The definition of the **FILETIME** structure is in the _Win32 Programmer's Reference_ and in the MAPI header file Mapidefs.h. MAPI defines the structure conditionally to make sure that it is defined when the Win32 definition is unavailable. Read more on docs.microsoft.com. > Low-order 32 bits of the file time value. > High-order 32 bits of the file time value. Adapter to use when owning classes cannot directly implement . Whenever you need to keep the owning object from being finalized during interop calls, use on the . This is the typed equivalent of . Marshalling doesn't know this, and while one could write a custom marshaler, we want our imports to do no marshalling for performance and trimming reasons. The **HRESULT** data type is the same as the [SCODE](scode.md) data type. An **HRESULT** value consists of the following fields: - A 1-bit code indicating severity, where zero represents success and 1 represents failure. - A 4-bit reserved value. - An 11-bit code indicating responsibility for the error or warning, also known as a facility code. - A 16-bit code describing the error or warning. Most MAPI interface methods and functions return **HRESULT** values to provide detailed cause formation. **HRESULT** values are also used widely in OLE interface methods. OLE provides several macros for converting between **HRESULT** values and **SCODE** values, another common data type for error handling. > [!NOTE] > In 64-bit MAPI, **HRESULT** is still a 32-bit value. For information about the OLE use of **HRESULT** values, see the *OLE Programmer's Reference*. For more information about the use of these values in MAPI, see [Error Handling](error-handling-in-mapi.md) and any of the following interface methods: [IABLogon::GetLastError](iablogon-getlasterror.md) [IMAPISupport::GetLastError](imapisupport-getlasterror.md) [IMAPIControl::GetLastError](imapicontrol-getlasterror.md) [IMAPITable::GetLastError](imapitable-getlasterror.md) [IMAPIProp::GetLastError](imapiprop-getlasterror.md) [IMAPIViewAdviseSink::OnPrint](imapiviewadvisesink-onprint.md) Read more on docs.microsoft.com. Extracts the facility code of the HRESULT. [HRESULT_FACILITY] Extracts the code portion of the HRESULT. [HRESULT_CODE] if the HRESULT represents an NTSTATUS code. Extracts the code. Check before calling this method. Converts a Win32 error code into an HRESULT. [HRESULT_FROM_WIN32] There is no associated handler for the given item registered by the specified application. (Windows Jump List) Object required. Visual Basic 6 and VBA raise this when objects have been collected or values aren't actually or object pointers. Seen in various places as E_UNKNOWNWORDERROR, VBA_E_NOTOBJECT, or the VB native EBERR_NotObject. is used for all VB errors raised as s. Object required (Error 424) Closing Word when a search is running was a way this could be generated per legacy comments. A pointer to the IErrorInfo interface that provides more information about the error. You can specify to use the current IErrorInfo interface, or new IntPtr(-1) to ignore the current IErrorInfo interface and construct the exception just from the error code. , if it does not reflect an error. The operation could not be completed. Learn more about this API from docs.microsoft.com. Documentation varies per use. Refer to each: IMbnConnectionContextEvents.OnSetProvisionedContextComplete, IMbnServiceActivationEvents.OnActivationComplete, IMbnSmsEvents.OnSmsSendComplete. Documentation varies per use. Refer to each: IMbnConnectionContextEvents.OnSetProvisionedContextComplete, IMbnConnectionEvents.OnConnectComplete, IMbnPinEvents.OnChangeComplete, IMbnPinEvents.OnDisableComplete, IMbnPinEvents.OnEnableComplete, IMbnPinEvents.OnEnterComplete, IMbnPinEvents.OnUnblockComplete, IMbnPinManagerEvents.OnGetPinStateComplete, IMbnRadioEvents.OnSetSoftwareRadioStateComplete, IMbnServiceActivationEvents.OnActivationComplete, IMbnSmsEvents.OnSetSmsConfigurationComplete, IMbnSmsEvents.OnSmsDeleteComplete, IMbnSmsEvents.OnSmsReadComplete, IMbnSmsEvents.OnSmsSendComplete. Places the window at the top of the Z order. Learn more about this API from docs.microsoft.com. Places the window at the bottom of the Z order. If the hWnd parameter identifies a topmost window, the window loses its topmost status and is placed at the bottom of all other windows. Learn more about this API from docs.microsoft.com. Places the window above all non-topmost windows. The window maintains its topmost position even when it is deactivated. Learn more about this API from docs.microsoft.com. Places the window above all non-topmost windows (that is, behind all topmost windows). This flag has no effect if the window is already a non-topmost window. Learn more about this API from docs.microsoft.com. Used to abstract access to classes that contain a potentially owned handle. The key benefit of this is that we can keep the owning class from being collected during interop calls. wraps arbitrary owners with target handles. Having this interface allows implicit use of the classes (such as System.Windows.Forms.Control) that meet this common pattern in interop and encourages correct alignment with the proper owner. Note that keeping objects alive is necessary ONLY when the object has a finalizer that will explicitly close the handle. When implementing P/Invoke wrappers that take this interface they should not directly take , but should take a generic "T" that is constrained to IHandle{T}. Doing it this way prevents boxing of structs. The "T" parameters should also be marked as to allow structs to be passed by reference instead of by value. When implementing this on a struct it is important that either the struct itself is marked as readonly or these properties are to avoid extra struct copies. Owner of the that might close it when finalized. Default is the implementer. This allows decoupling the owner from the provider and avoids boxing when is on a struct. See for a concrete usage. Used to indicate ownership of a native resource pointer. This should never be put on a struct. A pointer to a null-terminated, constant character string. A pointer to the first character in the string. The content should be considered readonly, as it was typed as constant in the SDK. Gets the number of characters up to the first null character (exclusive). Returns a with a copy of this character array, up to the first null character (exclusive). A , or if is . Returns a span of the characters in this string, up to the first null character (exclusive). The POINTS structure defines the x- and y-coordinates of a point. The POINTS structure is similar to the POINT and POINTL structures. The difference is that the members of the POINTS structure are of type SHORT, while those of the other two structures are of type LONG. Specifies the x-coordinate of the point. Specifies the y-coordinate of the point. The length of the string when it is a null separated list of values that is terminated by a double null. Does not include the final double null. Returns a span of the characters in this string, up to the first null character (exclusive). The RECT structure defines a rectangle by the coordinates of its upper-left and lower-right corners. The RECT structure is identical to the RECTL structure. Specifies the x-coordinate of the upper-left corner of the rectangle. Specifies the y-coordinate of the upper-left corner of the rectangle. Specifies the x-coordinate of the lower-right corner of the rectangle. Specifies the y-coordinate of the lower-right corner of the rectangle. Finalizable wrapper for COM pointers that gives agile access to the specified interface. This class should be used to hold all COM pointers that are stored as fields to ensure that they are safely finalized when needed. Finalization should be avoided whenever possible for performance and timely resource release (that is, this class should be disposed). Fields should be nulled out before calling . Releasing the COM pointer during disposal can result in callbacks to containing classes. Rather than evaluate the risk of this for every class, always follow this pattern. facilitates doing this safely. Creates an for the given . The COM interface pointer. Indicates whether to take ownership of the interface. If `` this object will own the ref count. The amount of memory pressure to add. is used to help the GC know that this object is holding onto native memory. This is most useful for objects that can be created in large quantities, particularly if they are not disposable. Setting to `` will ensure that this object takes responsibility for releasing the COM interface when it is no longer needed. This is done by calling after the GIT adds a ref to the interface. Other options were explored for ensuring that pending finalizers are not out of control besides . Caching the interface pointers in a static collection was considered, but this had no impact on the HtmlElement scenario, which would create a new COM object for every element access. Tracking creation counts and forcing the Finalizer to run was also considered, but that takes too much responsibility away from the GC- better to let it make the decision based on our additional pressure. Returns if has the same pointer this was created from. Gets the default interface. Throws if failed. Gets the specified interface. Throws if failed. Tries to get the default interface. Tries to get the specified interface. Gets the managed object using the pointer this was created from. Simple list for "typed" COM struct pointer storage. Prevents nulls. Doesn't implement generic interfaces as pointer types can't be used as generic arguments. Lifetime management struct for a native COM pointer. Meant to be utilized in a statement to ensure is called when going out of scope with the using. This struct has implicit conversions to T** and void** so it can be passed directly to out methods. For example: using ComScope<IUnknown> unknown = new(null); comObject->QueryInterface(&iid, unknown); Take care to NOT make copies of the struct to avoid accidental over-release. This should be one of the struct COM definitions as generated by CsWin32. Ideally we'd constrain to or some other interface tag to enforce that this is being used around a struct that is actually a COM wrapper. Tries querying the requested interface into a new . The result of the query. Queries the requested interface into a new . Attempt to create a from the given COM interface. Create a from the given COM interface. Throws on failure. Simple helper for checking if a given interface is supported. Only use this if you don't intend to use the interface, otherwise use . Wrapper for the COM global interface table. Registers the given in the global interface table. This decrements the ref count so that the entry in the table will "own" the interface (as it increments the ref count). The cookie used to refer to the interface in the table. Gets an agile interface for the that was given back by Revokes the interface registered with . This will decrement the ref count for the interface. Creates a new instance of an for that uses the Global Interface Table. The returned instance should not be cached. Strategy for that uses the . Gets a pointer to the IID for the given . Gets a reference to the IID for the given . Empty (GUID_NULL in docs). A pointer to a null-terminated, constant, ANSI character string. A pointer to the first character in the string. The content should be considered readonly, as it was typed as constant in the SDK. Gets the number of characters up to the first null character (exclusive). Returns a with a copy of this character array, decoding as UTF-8. A , or if is . Returns a span of the characters in this string, up to the first null character (exclusive). The POINTL structure defines the x- and y-coordinates of a point. The POINTL structure is identical to the POINT structure. Specifies the x-coordinate of the point. Specifies the y-coordinate of the point. Returns a span of the characters in this string, up to the first null character (exclusive). The SIZE structure defines the width and height of a rectangle. The rectangle dimensions stored in this structure can correspond to viewport extents, window extents, text extents, bitmap dimensions, or the aspect-ratio filter for some extended functions. Specifies the rectangle's width. The units depend on which function uses this structure. Specifies the rectangle's height. The units depend on which function uses this structure. Helper to ensure GDI+ is initialized before making calls. Attempts to ensure that GGI+ is initialized. Returns if GDI+ has been started. This should be called anywhere you make calls to GDI+ where you don't already have a GDI+ handle. In System.Drawing.Common, this is done in the PInvoke static constructor so it is not necessary for methods defined there. https://github.com/microsoft/CsWin32/issues/1308 tracks a proposal to make this more automatic. Returns if GDI+ has been started. This section lists the styles, in addition to standard window styles, supported by status bar controls. Learn more about this API from docs.microsoft.com. Buffer for values. Uses the stack for buffer sizes up to 16. Use in a statement. Helper to scope lifetime of an HDC retrieved via Use in a statement. If you must pass this around, always pass by to avoid duplicating the handle and risking a double EndPaint. Helper to scope lifetime of a created via Deletes the (if any) when disposed. Use in a statement. If you must pass this around, always pass by to avoid duplicating the handle and risking a double delete. Creates a bitmap using Creates a bitmap compatible with the given via Helper to scope the lifetime of a . Use in a statement. If you must pass this around, always pass by to avoid duplicating the handle and risking a double delete. Creates a solid brush based on the using . Helper to scope lifetime of an HDC retrieved via CreateDC/CreateCompatibleDC. Deletes the HDC (if any) when disposed. Use in a statement. If you must pass this around, always pass by to avoid duplicating the handle and risking a double delete. Creates a compatible HDC for using . Passing a HDC will use the current screen. Helper to scope the lifetime of a . Use in a statement. If you must pass this around, always pass by to avoid duplicating the handle and risking a double delete. Creates a solid pen based on the and using . The DEVMODEW structure is used for specifying characteristics of display and print devices in the Unicode (wide) character set. The DEVMODEW structure is the Unicode version of the DEVMODE structure (described in the Microsoft Windows SDK documentation). While applications can use either the ANSI or Unicode version of the structure, drivers are required to use the Unicode version. For printer drivers, the DEVMODEW structure is used for specifying printer characteristics required by a print document. It is also used for specifying a printer's default characteristics. Immediately following a DEVMODEW structure's defined members (often referred to as its public members), there can be a set of driver-defined members (often referred to as private DEVMODEW members). The driver supplies the size, in bytes, of this private area in dmDriverExtra. Driver-defined private members are for exclusive use by the driver. The starting address for the private members can be referenced using the dmSize member as follows: This doc was truncated. Read more on docs.microsoft.com. For a display, specifies the name of the display driver's DLL; for example, "perm3dd" for the 3Dlabs Permedia3 display driver. For a printer, specifies the "friendly name"; for example, "PCL/HP LaserJet" in the case of PCL/HP LaserJet. If the name is greater than CCHDEVICENAME characters in length, the spooler truncates it to fit in the array. Read more on docs.microsoft.com. Specifies the version number of this DEVMODEW structure. The current version number is identified by the DM_SPECVERSION constant in wingdi.h. For a printer, specifies the printer driver version number assigned by the printer driver developer. Display drivers can set this member to DM_SPECVERSION. Read more on docs.microsoft.com. Specifies the size in bytes of the public DEVMODEW structure, not including any private, driver-specified members identified by the dmDriverExtra member. Specifies the number of bytes of private driver data that follow the public structure members. If a device driver does not provide private DEVMODEW members, this member should be set to zero. Specifies bit flags identifying which of the following DEVMODEW members are in use. For example, the DM_ORIENTATION flag is set when the dmOrientation member contains valid data. The DM_XXX flags are defined in wingdi.h. For printers, specifies whether a color printer should print color or monochrome. This member can be one of DMCOLOR_COLOR or DMCOLOR_MONOCHROME. This member is not used for displays. Read more on docs.microsoft.com. For printers, specifies the y resolution of the printer, in DPI. If this member is used, the dmPrintQuality member specifies the x resolution. This member is not used for displays. Read more on docs.microsoft.com. For printers, specifies how TrueType fonts should be printed. This member must be one of the DMTT-prefixed constants defined in wingdi.h. This member is not used for displays. Read more on docs.microsoft.com. For printers, specifies the name of the form to use; such as "Letter" or "Legal". This must be a name that can be obtain by calling the Win32 EnumForms function (described in the Microsoft Window SDK documentation). This member is not used for displays. Read more on docs.microsoft.com. For displays, specifies the number of logical pixels per inch of a display device and should be equal to the ulLogPixels member of the GDIINFO structure. This member is not used for printers. Read more on docs.microsoft.com. For displays, specifies the color resolution, in bits per pixel, of a display device. This member is not used for printers. Read more on docs.microsoft.com. For displays, specifies the width, in pixels, of the visible device surface. This member is not used for printers. Read more on docs.microsoft.com. For displays, specifies the height, in pixels, of the visible device surface. This member is not used for printers. Read more on docs.microsoft.com. For displays, specifies the frequency, in hertz, of a display device in its current mode. This member is not used for printers. Read more on docs.microsoft.com. Specifies one of the DMICMMETHOD-prefixed constants defined in wingdi.h. Specifies one of the DMICM-prefixed constants defined in wingdi.h. Specifies one of the DMMEDIA-prefixed constants defined in wingdi.h. Specifies one of the DMDITHER-prefixed constants defined in wingdi.h. Is reserved for system use and should be ignored by the driver. Is reserved for system use and should be ignored by the driver. Is reserved for system use and should be ignored by the driver. Is reserved for system use and should be ignored by the driver. Helper to scope lifetime of an retrieved via and . Releases the (if any) when disposed. Use in a statement. If you must pass this around, always pass by to avoid duplicating the handle and risking a double release. Creates a using . GetWindowDC calls GetDCEx(hwnd, null, DCX_WINDOW | DCX_USESTYLE). GetDC calls GetDCEx(hwnd, null, DCX_USESTYLE) when given a handle. (When given null it has additional logic, and can't be replaced directly by GetDCEx. Creates a DC scope for the primary monitor (not the entire desktop). is the API to get the DC for the entire desktop. Creates a compatible bitmap copying the content of the current bitmap. Used when you must keep a handle to an in a field. Avoid keeping HDC handles in fields when possible. Take ownership from a . Defines the attributes of a font. (LOGFONTW) The following situations do not support ClearType antialiasing: This doc was truncated. Read more on docs.microsoft.com. Type: LONG Specifies the height, in logical units, of the font's character cell or character. The character height value (also known as the em height) is the character cell height value minus the internal-leading value. The font mapper interprets the value specified in lfHeight in the following manner. This doc was truncated. Read more on docs.microsoft.com. Type: LONG Specifies the average width, in logical units, of characters in the font. If lfWidth is not zero, the aspect ratio of the device is matched against the digitization aspect ratio of the available fonts to find the closest match, determined by the absolute value of the difference. Read more on docs.microsoft.com. Type: LONG Specifies the angle, in tenths of degrees, between the escapement vector and the x-axis of the device. The escapement vector is parallel to the base line of a row of text. The lfEscapement member specifies both the escapement and orientation. You should set lfEscapement and lfOrientation to the same value. Read more on docs.microsoft.com. Type: LONG Specifies the angle, in tenths of degrees, between each character's base line and the x-axis of the device. Read more on docs.microsoft.com. Type: LONG Specifies the weight of the font in the range 0 through 1000. For example, 400 is normal and 700 is bold. If this value is zero, a default weight is used. The following values are defined in Wingdi.h for convenience. This doc was truncated. Read more on docs.microsoft.com. Type: BYTE TRUE to specify an italic font. Read more on docs.microsoft.com. Type: BYTE TRUE to specify an underlined font. Read more on docs.microsoft.com. Type: BYTE TRUE to specify a strikeout font. Read more on docs.microsoft.com. Type: BYTE Specifies the character set. The following values are predefined: This doc was truncated. Read more on docs.microsoft.com. Type: BYTE Type: BYTE Type: BYTE Type: BYTE Type: TCHAR[LF_FACESIZE] Specifies a null-terminated string that specifies the typeface name of the font. The length of this string must not exceed 32 characters, including the terminating null character. The EnumFontFamilies function can be used to enumerate the typeface names of all currently available fonts. If lfFaceName is an empty string, GDI uses the first font that matches the other specified attributes. Read more on docs.microsoft.com. Helper to scope creating regions. Deletes the region when disposed. Use in a statement. If you must pass this around, always pass by to avoid duplicating the handle and risking a double deletion. Creates a region with the given rectangle via . Creates a region with the given rectangle via . Creates a clipping region copy via for the given device context. Handle to a device context to copy the clipping region from. Creates a region scope with the given . Returns true if this represents a null HRGN. Clears the handle. Use this to hand over ownership to another entity. The RGNDATAHEADER structure describes the data returned by the GetRegionData function. Learn more about this API from docs.microsoft.com. The size, in bytes, of the header. The type of region. This value must be RDH_RECTANGLES. The number of rectangles that make up the region. The size of the RGNDATA buffer required to receive the RECT structures that make up the region. If the size is not known, this member can be zero. A bounding rectangle for the region in logical units. Helper to scope lifetime of a saved device context state. Use in a statement. If you must pass this around, always pass by to avoid duplicating the handle and risking a double restore. The state that is saved includes ICM (color management), palette, path drawing state, and other objects that are selected into the DC (bitmap, brush, pen, clipping region, font). Ideally saving the entire DC state can be avoided for simple drawing operations and relying on restoring individual state pieces can be done instead (putting back the original pen, etc.). Saves the device context state using . Helper to scope selecting a GDI object into an . Restores the original object into the when disposed. Use in a statement. If you must pass this around, always pass by to avoid duplicating the handle and risking a double selection. Selects into the given using . Helper to scope palette selection. Use in a statement. If you must pass this around, always pass by to avoid duplicating the handle and risking a double palette reset. Helper to scope selecting a given background color into a HDC. Restores the original background color into the HDC when disposed. Use in a statement. If you must pass this around, always pass by to avoid duplicating the handle and resetting multiple times. Sets text color in the given using . Helper to scope selecting a given background mix mode into a HDC. Restores the original mix mode into the HDC when disposed. Use in a statement. If you must pass this around, always pass by to avoid duplicating the handle and resetting multiple times. Selects into the given . Helper to scope selecting a given mapping mode into a HDC. Restores the original mapping mode into the HDC when disposed. Use in a statement. If you must pass this around, always pass by to avoid duplicating the handle and resetting multiple times. Sets the in the given using . Helper to scope selecting a given foreground mix mode into a HDC. Restores the original mix mode into the HDC when disposed. Use in a statement. If you must pass this around, always pass by to avoid duplicating the handle and resetting multiple times. Selects into the given using . Helper to scope selecting a given text alignment mode into a HDC. Restores the original text alignment mode into the HDC when disposed. Use in a statement. If you must pass this around, always pass by to avoid duplicating the handle and resetting multiple times. Sets in the given using . Helper to scope selecting a given foreground text color into a HDC. Restores the original text color into into the HDC when disposed. Use in a statement. If you must pass this around, always pass by to avoid duplicating the handle and resetting multiple times. Sets text color in the given using . A BITMAPINFOHEADER structure that contains information about the dimensions of color format. . Read more on docs.microsoft.com. The bmiColors member contains one of the following: This doc was truncated. Read more on docs.microsoft.com. Computes the amount of memory that must be allocated to store this struct, including the specified number of elements in the variable length inline array at the end. The BITMAPINFOHEADER structure contains information about the dimensions and color format of a device-independent bitmap (DIB).

Color Tables

The BITMAPINFOHEADER structure may be followed by an array of palette entries or color masks. The rules depend on the value of biCompression. This doc was truncated. Read more on docs.microsoft.com. Specifies the number of bytes required by the structure. This value does not include the size of the color table or the size of the color masks, if they are appended to the end of structure. See Remarks. Specifies the width of the bitmap, in pixels. For information about calculating the stride of the bitmap, see Remarks. Specifies the height of the bitmap, in pixels. This doc was truncated. Read more on docs.microsoft.com. Specifies the number of planes for the target device. This value must be set to 1. Specifies the number of bits per pixel (bpp). For uncompressed formats, this value is the average number of bits per pixel. For compressed formats, this value is the implied bit depth of the uncompressed image, after the image has been decoded. For compressed video and YUV formats, this member is a FOURCC code, specified as a DWORD in little-endian order. For example, YUYV video has the FOURCC 'VYUY' or 0x56595559. For more information, see FOURCC Codes. For uncompressed RGB formats, the following values are possible: This doc was truncated. Read more on docs.microsoft.com. Specifies the size, in bytes, of the image. This can be set to 0 for uncompressed RGB bitmaps. Specifies the horizontal resolution, in pixels per meter, of the target device for the bitmap. Specifies the vertical resolution, in pixels per meter, of the target device for the bitmap. Specifies the number of color indices in the color table that are actually used by the bitmap. See Remarks for more information. Specifies the number of color indices that are considered important for displaying the bitmap. If this value is zero, all colors are important. The ENHMETARECORD structure contains data that describes a graphics device interface (GDI) function used to create part of a picture in an enhanced-format metafile. Learn more about this API from docs.microsoft.com. The record type. The size of the record, in bytes. An array of parameters passed to the GDI function identified by the record. Computes the amount of memory that must be allocated to store this struct, including the specified number of elements in the variable length inline array at the end. The HANDLETABLE structure is an array of handles, each of which identifies a graphics device interface (GDI) object. Learn more about this API from docs.microsoft.com. An array of handles. Computes the amount of memory that must be allocated to store this struct, including the specified number of elements in the variable length inline array at the end. The MONITORINFO structure contains information about a display monitor.The GetMonitorInfo function stores information in a MONITORINFO structure or a MONITORINFOEX structure.The MONITORINFO structure is a subset of the MONITORINFOEX structure. Learn more about this API from docs.microsoft.com. The size of the structure, in bytes. Set this member to sizeof ( MONITORINFO ) before calling the GetMonitorInfo function. Doing so lets the function determine the type of structure you are passing to it. Read more on docs.microsoft.com. A RECT structure that specifies the display monitor rectangle, expressed in virtual-screen coordinates. Note that if the monitor is not the primary display monitor, some of the rectangle's coordinates may be negative values. A RECT structure that specifies the work area rectangle of the display monitor, expressed in virtual-screen coordinates. Note that if the monitor is not the primary display monitor, some of the rectangle's coordinates may be negative values. A set of flags that represent attributes of the display monitor. The following flag is defined. This doc was truncated. Read more on docs.microsoft.com. The MONITORINFOEX structure contains information about a display monitor.The GetMonitorInfo function stores information into a MONITORINFOEX structure or a MONITORINFO structure.The MONITORINFOEX structure is a superset of the MONITORINFO structure. (Unicode) > [!NOTE] > The winuser.h header defines MONITORINFOEX as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see [Conventions for Function Prototypes](/windows/win32/intl/conventions-for-function-prototypes). Read more on docs.microsoft.com. A string that specifies the device name of the monitor being used. Most applications have no use for a display monitor name, and so can save some bytes by using a MONITORINFO structure. The PAINTSTRUCT structure contains information for an application. This information can be used to paint the client area of a window owned by that application. Learn more about this API from docs.microsoft.com. A handle to the display DC to be used for painting. Indicates whether the background must be erased. This value is nonzero if the application should erase the background. The application is responsible for erasing the background if a window class is created without a background brush. For more information, see the description of the hbrBackground member of the WNDCLASS structure. A RECT structure that specifies the upper left and lower right corners of the rectangle in which the painting is requested, in device units relative to the upper-left corner of the client area. Reserved; used internally by the system. Reserved; used internally by the system. Reserved; used internally by the system. Specifies the color and usage of an entry in a logical palette. Learn more about this API from docs.microsoft.com. Type: BYTE The red intensity value for the palette entry. Read more on docs.microsoft.com. Type: BYTE The green intensity value for the palette entry. Read more on docs.microsoft.com. Type: BYTE The blue intensity value for the palette entry. Read more on docs.microsoft.com. 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. Read more on docs.microsoft.com. The RGBQUAD structure describes a color consisting of relative intensities of red, green, and blue. The bmiColors member of the BITMAPINFO structure consists of an array of RGBQUAD structures. The intensity of blue in the color. The intensity of green in the color. The intensity of red in the color. This member is reserved and must be zero. The RGNDATA structure contains a header and an array of rectangles that compose a region. The rectangles are sorted top to bottom, left to right. They do not overlap. Learn more about this API from docs.microsoft.com. A RGNDATAHEADER structure. The members of this structure specify the type of region (whether it is rectangular or trapezoidal), the number of rectangles that make up the region, the size of the buffer that contains the rectangle structures, and so on. Specifies an arbitrary-size buffer that contains the RECT structures that make up the region. Computes the amount of memory that must be allocated to store this struct, including the specified number of elements in the variable length inline array at the end. The XFORM structure specifies a world-space to page-space transformation. The following list describes how the members are used for each operation. This doc was truncated. Read more on docs.microsoft.com. The following. This doc was truncated. Read more on docs.microsoft.com. The following. This doc was truncated. Read more on docs.microsoft.com. The following. This doc was truncated. Read more on docs.microsoft.com. The following. This doc was truncated. Read more on docs.microsoft.com. The horizontal translation component, in logical units. The vertical translation component, in logical units. Helper to scope lifetime of a GDI object. Deletes the given object (if any) when disposed. Use in a statement. If you must pass this around, always pass by to avoid duplicating the handle and risking a double deletion. The object to be deleted when the scope closes. Simple internal wrapper that enables showing the message identifier string in the debugger. Returns the symbolic name of the message value, or null if it isn't one of the existing constants. Contains extern methods from "COMCTL32.dll". Contains extern methods from "GDI32.dll". Contains extern methods from "gdiplus.dll". Contains extern methods from "KERNEL32.dll". Contains extern methods from "OLE32.dll". Contains extern methods from "OLEAUT32.dll". Contains extern methods from "SHELL32.dll". Contains extern methods from "USER32.dll". Enumerates all nonchild windows in the current thread. Dynamic wrapper for GetWindowLong that works on both 32 and 64 bit. GetWindowLong documentation. The maximum length for lpszClassName is 256. If lpszClassName is greater than the maximum length, the RegisterClassEx function will fail. Read more on https://learn.microsoft.com. The maximum name for an ATOM is 255 characters, which is where this limitation comes from. There is no public define, internally it is RTL_ATOM_MAXIMUM_NAME_LENGTH. Tries to get system parameter info for the dpi. dpi is ignored if "SystemParametersInfoForDpi()" API is not available on the OS that this application is running. Destroys a property sheet page. An application must call this function for pages that have not been passed to the PropertySheet function. Type: BOOL Returns nonzero if successful, or zero otherwise. Learn more about this API from docs.microsoft.com. Documentation varies per use. Refer to each: ImageList_DrawEx, ImageList_DrawEx, IMAGELISTDRAWPARAMS, IMAGELISTDRAWPARAMS, IMAGELISTDRAWPARAMS, IMAGELISTDRAWPARAMS. Documentation varies per use. Refer to each: ImageList_DrawEx, ImageList_DrawEx, IMAGELISTDRAWPARAMS, IMAGELISTDRAWPARAMS, IMAGELISTDRAWPARAMS, IMAGELISTDRAWPARAMS. Scrolls the caret into view in an edit control. You can send this message to either an edit control or a rich edit control. The return value is not meaningful. **Rich Edit:** Supported in Microsoft Rich Edit 1.0 and later. For information about the compatibility of rich edit versions with the various system versions, see [About Rich Edit Controls](about-rich-edit-controls.md). EM_SETLIMITTEXT message - Sets the text limit of an edit control. This message does not return a value. The **EM\_SETLIMITTEXT** message limits only the text the user can enter. It does not affect any text already in the edit control when the message is sent, nor does it affect the length of the text copied to the edit control by the [**WM\_SETTEXT**](/windows/desktop/winmsg/wm-settext) message. If an application uses the **WM\_SETTEXT** message to place more text into an edit control than is specified in the **EM\_SETLIMITTEXT** message, the user can edit the entire contents of the edit control. Before **EM\_SETLIMITTEXT** is called, the default limit for the amount of text a user can enter in an edit control is 32,767 characters. For single-line edit controls, the text limit is either 0x7FFFFFFE bytes or the value of the *wParam* parameter, whichever is smaller. For multiline edit controls, this value is either 1 bytes or the value of the *wParam* parameter, whichever is smaller. **Rich Edit:** Supported in Microsoft Rich Edit 1.0 and later. Use the message [**EM\_EXLIMITTEXT**](em-exlimittext.md) for text length values greater than 64,000. For information about the compatibility of rich edit versions with the various system versions, see [About Rich Edit Controls](about-rich-edit-controls.md). Read more on docs.microsoft.com. Gets the current text limit for an edit control. You can send this message to either an edit control or a rich edit control. The return value is the text limit. **Edit controls, Rich Edit 2.0 and later:** The text limit is the maximum amount of text, in **TCHAR**s, that the control can contain. For ANSI text, this is the number of bytes; for Unicode text, this is the number of characters. Two documents with the same character limit will yield the same text limit, even if one is ANSI and the other is Unicode. **Rich Edit 1.0:** The text limit is the maximum amount of text, in bytes, that the rich edit control can contain. **Rich Edit:** Supported in Microsoft Rich Edit 1.0 and later. For information about the compatibility of rich edit versions with the various system versions, see [About Rich Edit Controls](about-rich-edit-controls.md). Read more on docs.microsoft.com. Retrieves the client area coordinates of a specified character in an edit control. You can send this message to either an edit control or a rich edit control. **Rich Edit 1.0 and 3.0:** The return value is not used. **Edit controls and Rich Edit 2.0:** The return value contains the client area coordinates of the character. The [**LOWORD**](/previous-versions/windows/desktop/legacy/ms632659(v=vs.85)) contains the horizontal coordinate and the [**HIWORD**](/previous-versions/windows/desktop/legacy/ms632657(v=vs.85)) contains the vertical coordinate. A returned coordinate can be a negative value if the specified character is not displayed in the edit control's client area. The coordinates are truncated to integer values. If the character is a line delimiter, the returned coordinates indicate a point just beyond the last visible character in the line. If the specified index is greater than the index of the last character in the control, the control returns -1. **Rich Edit 3.0 and later:** For backward compatibility, Microsoft Rich Edit 3.0 supports the syntax used by Microsoft Rich Edit 2.0. If Microsoft Rich Edit 3.0 detects that *wParam* is not a valid [**POINTL**](/windows/win32/api/windef/ns-windef-pointl) pointer, it assumes the message was sent using the Microsoft Rich Edit 2.0 syntax. In this case, it uses the return value to return the coordinates. **Rich Edit:** Supported in Microsoft Rich Edit 1.0 and later. For information about the compatibility of rich edit versions with the various system versions, see [About Rich Edit Controls](about-rich-edit-controls.md). Read more on docs.microsoft.com. Gets information about the character closest to a specified point in the client area of an edit control. You can send this message to either an edit control or a rich edit control. **Rich edit controls:** The return value specifies the zero-based character index of the character nearest the specified point. The return value indicates the last character in the edit control if the specified point is beyond the last character in the control. **Edit controls:** The [**LOWORD**](/previous-versions/windows/desktop/legacy/ms632659(v=vs.85)) specifies the zero-based index of the character nearest the specified point. This index is relative to the beginning of the control, not the beginning of the line. If the specified point is beyond the last character in the edit control, the return value indicates the last character in the control. The [**HIWORD**](/previous-versions/windows/desktop/legacy/ms632657(v=vs.85)) specifies the zero-based index of the line that contains the character. For single-line edit controls, this value is zero. The index indicates the line delimiter if the specified point is beyond the last visible character in a line. **Rich Edit:** Supported in Microsoft Rich Edit 1.0 and later. For information about the compatibility of rich edit versions with the various system versions, see [About Rich Edit Controls](about-rich-edit-controls.md). If a point is passed to **EM\_CHARFROMPOS** as the *lParam* and the point is outside the bounds of the edit control, then the *lResult* is (65535, 65535). Read more on docs.microsoft.com. Sets the textual cue, or tip, that is displayed by the edit control to prompt the user for information. If the message succeeds, it returns **TRUE**. Otherwise it returns **FALSE**. An edit control that is used to begin a search may display "Enter search here" in gray text as a textual cue. When the user clicks the text, the text goes away and the user can type. You cannot set a cue banner on a multiline edit control or on a rich edit control. > [!Note] > To use this API, you must provide a manifest specifying Comclt32.dll version 6.0. For more information on manifests, see [Enabling Visual Styles](cookbook-overview.md). Read more on docs.microsoft.com. Gets the text that is displayed as the textual cue, or tip, in an edit control. Returns **TRUE** if successful or **FALSE** otherwise. > [!Note] > To use this message, you must provide a manifest specifying Comclt32.dll version 6.0. For more information on manifests, see [Enabling Visual Styles](cookbook-overview.md). Read more on docs.microsoft.com. The EM\_SHOWBALLOONTIP message displays a balloon tip associated with an edit control. If the message succeeds, it returns **TRUE**. Otherwise it returns **FALSE**. > [!Note] > To use this message, you must provide a manifest specifying Comclt32.dll version 6.0. For more information on manifests, see [Enabling Visual Styles](cookbook-overview.md). Read more on docs.microsoft.com. Hides any balloon tip associated with an edit control. If the message succeeds, it returns **TRUE**. Otherwise it returns **FALSE**. > [!Note] > To use this message, you must provide a manifest specifying Comclt32.dll version 6.0. For more information on manifests, see [Enabling Visual Styles](cookbook-overview.md). Read more on docs.microsoft.com. EM_SETHILITE message - Not implemented. Learn more about this API from docs.microsoft.com. EM\_GETHILITE message Learn more about this API from docs.microsoft.com. Prevents a single-line edit control from receiving keyboard focus. You can send this message explicitly or by using the Edit\_NoSetFocus macro. The return value is not used. This message is ignored if the edit control is not a single-line edit control. After this message is sent, the effect is permanent. Read more on docs.microsoft.com. Forces a single-line edit control to receive keyboard focus. You can send this message explicitly or by using the Edit\_TakeFocus macro. The return value is not used. This message is ignored if the edit control is not a single-line edit control. If the edit control previously received an [**EM\_NOSETFOCUS**](em-nosetfocus.md) message, the edit control will appear to have the focus without actually having it; otherwise, the edit control will receive focus. Read more on docs.microsoft.com. Informs the edit control to set extended styles. Send this message or use the macro Edit\_SetExtendedStyle. If this message succeeds, it returns **S\_OK**. Otherwise, it returns an **HRESULT** error code. The extended styles for an edit control have nothing to do with the extended styles used with function [**CreateWindowEx**](/windows/desktop/api/winuser/nf-winuser-createwindowexa) or function [**SetWindowLong**](/windows/desktop/api/winuser/nf-winuser-setwindowlonga). Retrieves the extended style for an edit control. Send this message explicitly or by using the Edit\_GetExtendedStyle macro. Returns the value of extended style.For more information on styles, see [Edit Control Extended Styles](edit-control-window-extended-styles.md). The extended styles for an edit control have nothing to do with the extended styles used with function [**CreateWindowEx**](/windows/desktop/api/winuser/nf-winuser-createwindowexa) or function [**SetWindowLong**](/windows/desktop/api/winuser/nf-winuser-setwindowlonga). Sets the end-of-line character used when a linebreak is inserted. If the operation succeeds, the return value is nonzero. If the operation fails, the return value is zero. When the end-of-line character set is **EC\_ENDOFLINE\_DETECTFROMCONTENT**, the edit control will only detect end-of-line characters supported according to its extended window style, see [Edit Control Extended Styles](edit-control-window-extended-styles.md). Retrieves the end-of-line character used when a linebreak is inserted. Send this message explicitly or by using the Edit\_GetEndOfLine macro. Returns the end-of-line character used by the edit control. This can be one of the following values. | Value | Meaning | |---------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------| |
**EC\_ENDOFLINE\_CRLF**
| The end-of-line character used for new linebreaks is carriage return followed by linefeed (CRLF).
| |
**EC\_ENDOFLINE\_CR**
| The end-of-line character used for new linebreaks is carriage return (CR).
| |
**EC\_ENDOFLINE\_LF**
| The end-of-line character used for new linebreaks is linefeed (LF).
| When the end-of-line character used is set to **EC\_ENDOFLINE\_DETECTFROMCONTENT** using [**Edit\_SetEndOfLine**](/windows/desktop/api/Commctrl/nf-commctrl-edit_setendofline), this message will return the detected end-of-line character. Enables or disables the "Search the web" feature and context menu entry. This message does not return a value. If you disable "Search the web" using this message, the [**EM\_SEARCHWEB**](em-searchweb.md) message has no effect. Opens the browser and performs a web search with the selected text as the search term. This message does not return a value. If the "Search the web" feature is disabled using the [**EM\_ENABLESEARCHWEB**](em-enablesearchweb.md) message, this message has no effect. Sets the zero-based index value of the position of the caret in an edit control. This message does not return a value. If the index is out of the range of the text in an edit control, the index will be adjusted to fit inside the range of the text. Gets the zero-based index of the position of the caret in an edit control. The return value is a zero-based index value of the position of the caret. Learn more about this API from docs.microsoft.com. Gets the index of the line that contains the specified character index in a multiline edit control, independently of how lines are displayed on the screen. The return value is the zero-based line number of the line containing the character index specified by *wParam*, independently of how lines are displayed on the screen. Learn more about this API from docs.microsoft.com. Gets the character index of the first character of a specified line in a multiline edit control, independently of how lines are displayed on the screen. The return value is the character index of the line specified in the *wParam* parameter, independently of how lines are displayed on the screen, or it is -1 if the specified line number is greater than the number of lines in the edit control. Learn more about this API from docs.microsoft.com. Retrieves the length, in characters, of a line in an edit control, independently of how lines are displayed on the screen. For multiline edit controls, the return value is the length, in **TCHAR**s, of the line specified by the *wParam* parameter, independently of how lines are displayed on the screen. It does not include the carriage-return or linefeed character at the end of the line. For single-line edit controls, the return value is the length, in **TCHAR**s, of the text in the edit control. If *wParam* is greater than the number of characters in the control, the return value is zero. Use the [**EM\_FILELINEINDEX**](em-lineindex.md) message to retrieve a character index for a given line number within a multiline edit control, independently of how lines are displayed on the screen. Copies a line of text from an edit control, independently of how lines are displayed on the screen, and places it in a specified buffer. The return value is the number of **TCHAR**s copied. The return value is zero if the line number specified by the *wParam* parameter is greater than the number of lines in the edit control. The copied line does not contain a terminating null character. Gets the number of lines in a multiline edit control, independently of how lines are displayed on the screen. The return value is an integer specifying the total number of text lines in the multiline edit control, independently of how lines are displayed on the screen. If the control has no text, the return value is 1. The return value will never be less than 1. The **EM\_GETFILELINECOUNT** message retrieves the total number of text lines, independently of how lines are displayed on the screen, not just the number of lines that are currently visible. Word-wrap does not change the number of lines this message returns, as this message works independently of how lines are displayed on the screen. Read more on docs.microsoft.com. Gets the starting and ending character positions (in TCHARs) of the current selection in an edit control. You can send this message to either an edit control or a rich edit control. The return value is a zero-based value with the starting position of the selection in the [**LOWORD**](/previous-versions/windows/desktop/legacy/ms632659(v=vs.85)) and the position of the first **TCHAR** after the last selected **TCHAR** in the [**HIWORD**](/previous-versions/windows/desktop/legacy/ms632657(v=vs.85)). If either of these values exceeds 65,535, the return value is -1. It is better to use the values returned in *wParam* and *lParam* because they are full 32-bit values. If there is no selection, the starting and ending values are both the position of the caret. **Rich edit controls:** You can also use the [**EM\_EXGETSEL**](em-exgetsel.md) message to retrieve the same information. **EM\_EXGETSEL** also returns starting and ending character positions as 32-bit values. **Rich Edit:** Supported in Microsoft Rich Edit 1.0 and later. For information about the compatibility of rich edit versions with the various system versions, see [About Rich Edit Controls](about-rich-edit-controls.md). Read more on docs.microsoft.com. Selects a range of characters in an edit control. You can send this message to either an edit control or a rich edit control. This message does not return a value. The start value can be greater than the end value. The lower of the two values specifies the character position of the first character in the selection. The higher value specifies the position of the first character beyond the selection. The start value is the anchor point of the selection, and the end value is the active end. If the user uses the SHIFT key to adjust the size of the selection, the active end can move but the anchor point remains the same. If the start is 0 and the end is -1, all the text in the edit control is selected. If the start is -1, any current selection is deselected. **Edit controls:** The control displays a flashing caret at the end position regardless of the relative values of start and end. **Rich Edit:** Supported in Microsoft Rich Edit 1.0 and later. For information about the compatibility of rich edit versions with the various system versions, see [About Rich Edit Controls](about-rich-edit-controls.md). If the edit control has the [**ES\_NOHIDESEL**](edit-control-styles.md) style, the selected text is highlighted regardless of whether the control has focus. Without the **ES\_NOHIDESEL** style, the selected text is highlighted only when the edit control has the focus. Read more on docs.microsoft.com. Gets the formatting rectangle of an edit control. The return value is not meaningful. You can modify the formatting rectangle of a multiline edit control by using the [**EM\_SETRECT**](em-setrect.md) and [**EM\_SETRECTNP**](em-setrectnp.md) messages. Under certain conditions, **EM\_GETRECT** might not return the exact values that [**EM\_SETRECT**](em-setrect.md) or [**EM\_SETRECTNP**](em-setrectnp.md) set it will be approximately correct, but it can be off by a few pixels. **Rich Edit:** Supported in Microsoft Rich Edit 1.0 and later. The formatting rectangle does not include the selection bar, which is an unmarked area to the left of each paragraph. When clicked, the selection bar selects the line. For information about the compatibility of rich edit versions with the various system versions, see [About Rich Edit Controls](about-rich-edit-controls.md). Read more on docs.microsoft.com. EM_SETRECT message - Sets the formatting rectangle of a multiline edit control. This message does not return a value. Setting *lParam* to **NULL** has no effect if a touch device is installed, or if **EM\_SETRECT** is sent from a thread that has a hook installed (see [**SetWindowsHookEx**](/windows/desktop/api/winuser/nf-winuser-setwindowshookexa)). In these cases, *lParam* should contain a valid pointer to a [**RECT**](/windows/win32/api/windef/ns-windef-rect) structure. The **EM\_SETRECT** message causes the text of the edit control to be redrawn. To change the size of the formatting rectangle without redrawing the text, use the [**EM\_SETRECTNP**](em-setrectnp.md) message. When an edit control is first created, the formatting rectangle is set to a default size. You can use the **EM\_SETRECT** message to make the formatting rectangle larger or smaller than the edit control window. If the edit control does not have a horizontal scroll bar, and the formatting rectangle is set to be larger than the edit control window, lines of text exceeding the width of the edit control window (but smaller than the width of the formatting rectangle) are clipped instead of wrapped. If the edit control contains a border, the formatting rectangle is reduced by the size of the border. If you are adjusting the rectangle returned by an [**EM\_GETRECT**](em-getrect.md) message, you must remove the size of the border before using the rectangle with the **EM\_SETRECT** message. **Rich Edit:** Supported in Microsoft Rich Edit 1.0 and later. The formatting rectangle does not include the selection bar, which is an unmarked area to the left of each paragraph. When the user clicks in the selection bar, the corresponding line is selected. For information about the compatibility of rich edit versions with the various system versions, see [About Rich Edit Controls](about-rich-edit-controls.md). Read more on docs.microsoft.com. EM_SETRECTNP message - Sets the formatting rectangle of a multiline edit control. This message does not return a value. **Rich Edit:** Supported in Microsoft Rich Edit 3.0 and later. For information about the compatibility of rich edit versions with the various system versions, see [About Rich Edit Controls](about-rich-edit-controls.md). Scrolls the text vertically in a multiline edit control. This message is equivalent to sending a WM\_VSCROLL message to the edit control. You can send this message to either an edit control or a rich edit control. If the message is successful, the [**HIWORD**](/previous-versions/windows/desktop/legacy/ms632657(v=vs.85)) of the return value is **TRUE**, and the [**LOWORD**](/previous-versions/windows/desktop/legacy/ms632659(v=vs.85)) is the number of lines that the command scrolls. The number returned may not be the same as the actual number of lines scrolled if the scrolling moves to the beginning or the end of the text. If the *wParam* parameter specifies an invalid value, the return value is **FALSE**. To scroll to a specific line or character position, use the [**EM\_LINESCROLL**](em-linescroll.md) message. To scroll the caret into view, use the [**EM\_SCROLLCARET**](em-scrollcaret.md) message. **Rich Edit:** Supported in Microsoft Rich Edit 1.0 and later. For information about the compatibility of rich edit versions with the various system versions, see [About Rich Edit Controls](about-rich-edit-controls.md). Read more on docs.microsoft.com. Scrolls the text in a multiline edit control. If the message is sent to a multiline edit control, the return value is **TRUE**. If the message is sent to a single-line edit control, the return value is **FALSE**. The control does not scroll vertically past the last line of text in the edit control. If the current line plus the number of lines specified by the *lParam* parameter exceeds the total number of lines in the edit control, the value is adjusted so that the last line of the edit control is scrolled to the top of the edit-control window. **Edit controls:** The **EM\_LINESCROLL** message scrolls the text vertically or horizontally in a multiline edit control. The **EM\_LINESCROLL** message can be used to scroll horizontally past the last character of any line. **Rich Edit:** Supported in Microsoft Rich Edit 1.0 and later. The **EM\_LINESCROLL** message scrolls the text vertically in a multiline edit control. For information about the compatibility of rich edit versions with the various system versions, see [About Rich Edit Controls](about-rich-edit-controls.md). Read more on docs.microsoft.com. Gets the state of an edit control's modification flag. The flag indicates whether the contents of the edit control have been modified. You can send this message to either an edit control or a rich edit control. If the contents of edit control have been modified, the return value is nonzero; otherwise, it is zero. The system automatically clears the modification flag to zero when the control is created. If the user changes the control's text, the system sets the flag to nonzero. You can send the [**EM\_SETMODIFY**](em-setmodify.md) message to the edit control to set or clear the flag. **Rich Edit:** Supported in Microsoft Rich Edit 1.0 and later. For information about the compatibility of rich edit versions with the various system versions, see [About Rich Edit Controls](about-rich-edit-controls.md). Read more on docs.microsoft.com. Sets or clears the modification flag for an edit control. The modification flag indicates whether the text within the edit control has been modified. You can send this message to either an edit control or a rich edit control. This message does not return a value. The system automatically clears the modification flag to zero when the control is created. If the user changes the control's text, the system sets the flag to nonzero. You can send the [**EM\_GETMODIFY**](em-getmodify.md) message to the edit control to retrieve the current state of the flag. **Rich Edit 1.0:** Objects created without the **REO\_DYNAMICSIZE** flag will lock in their extents when the modify flag is set to **FALSE**. **Rich Edit:** Supported in Microsoft Rich Edit 1.0 and later. For information about the compatibility of rich edit versions with the various system versions, see [About Rich Edit Controls](about-rich-edit-controls.md). Read more on docs.microsoft.com. Gets the number of lines in a multiline edit control. You can send this message to either an edit control or a rich edit control. The return value is an integer specifying the total number of text lines in the multiline edit control or rich edit control. If the control has no text, the return value is 1. The return value will never be less than 1. The **EM\_GETLINECOUNT** message retrieves the total number of text lines, not just the number of lines that are currently visible. If the Wordwrap feature is enabled, the number of lines can change when the dimensions of the editing window change. **Rich Edit:** Supported in Microsoft Rich Edit 1.0 and later. For information about the compatibility of rich edit versions with the various system versions, see [About Rich Edit Controls](about-rich-edit-controls.md). Read more on docs.microsoft.com. Gets the character index of the first character of a specified line in a multiline edit control. The return value is the character index of the line specified in the *wParam* parameter, or it is -1 if the specified line number is greater than the number of lines in the edit control. **Rich Edit:** Supported in Microsoft Rich Edit 1.0 and later. For information about the compatibility of rich edit versions with the various system versions, see [About Rich Edit Controls](about-rich-edit-controls.md). Sets the handle of the memory that will be used by a multiline edit control. This message does not return a value. Before an application sets a new memory handle, it should send an [**EM\_GETHANDLE**](em-gethandle.md) message to retrieve the handle of the current memory buffer and should free that memory. An edit control automatically reallocates the given buffer whenever it needs additional space for text, or it removes enough text so that additional space is no longer needed. Sending an **EM\_SETHANDLE** message clears the undo buffer ([**EM\_CANUNDO**](em-canundo.md) returns zero) and the internal modification flag ([**EM\_GETMODIFY**](em-getmodify.md) returns zero). The edit control window is redrawn. **Rich Edit:** The **EM\_SETHANDLE** message is not supported. Rich edit controls do not store text as a simple array of characters. Read more on docs.microsoft.com. Gets a handle of the memory currently allocated for a multiline edit control's text. The return value is a memory handle identifying the buffer that holds the content of the edit control. If an error occurs, such as sending the message to a single-line edit control, the return value is zero. If the function succeeds, the application can access the contents of the edit control by casting the return value to [**HLOCAL**](/windows/desktop/WinProg/windows-data-types) and passing it to [**LocalLock**](/windows/desktop/api/winbase/nf-winbase-locallock). **LocalLock** returns a pointer to a buffer that is a null-terminated array of **CHAR**s or **WCHAR**s, depending on whether an ANSI or Unicode function created the control. For example, if [**CreateWindowExA**](/windows/desktop/api/winuser/nf-winuser-createwindowexa) was used the buffer is an array of **CHAR**s, but if **CreateWindowExW** was used the buffer is an array of **WCHAR**s. The application may not change the contents of the buffer. To unlock the buffer, the application calls [**LocalUnlock**](/windows/desktop/api/winbase/nf-winbase-localunlock) before allowing the edit control to receive new messages. > [!Note] > For Comctl32.dll version 6, the buffer always contains an array of **WCHAR**s, regardless of whether an ANSI or Unicode function created the edit control. For more information on DLL versions, see [Common Control Versions](common-control-versions.md). If your application cannot abide by the restrictions imposed by **EM\_GETHANDLE**, use the [**GetWindowTextLength**](/windows/desktop/api/winuser/nf-winuser-getwindowtextlengtha) and [**GetWindowText**](/windows/desktop/api/winuser/nf-winuser-getwindowtexta) functions to copy the contents of the edit control into an application-provided buffer. **Rich Edit:** The **EM\_GETHANDLE** message is not supported. Rich edit controls do not store text as a simple array of characters. Read more on docs.microsoft.com. Gets the position of the scroll box (thumb) in the vertical scroll bar of a multiline edit control. You can send this message to either an edit control or a rich edit control. The return value is the position of the scroll box. **Rich Edit:** Supported in Microsoft Rich Edit 2.0 and later. For information about the compatibility of rich edit versions with the various system versions, see [About Rich Edit Controls](about-rich-edit-controls.md). Retrieves the length, in characters, of a line in an edit control. You can send this message to either an edit control or a rich edit control. For multiline edit controls, the return value is the length, in **TCHAR**s, of the line specified by the *wParam* parameter. For ANSI text, this is the number of bytes; for Unicode text, this is the number of characters. It does not include the carriage-return character at the end of the line. For single-line edit controls, the return value is the length, in **TCHAR**s, of the text in the edit control. If *wParam* is greater than the number of characters in the control, the return value is zero. Use the [**EM\_LINEINDEX**](em-lineindex.md) message to retrieve a character index for a given line number within a multiline edit control. **Rich Edit:** Supported in Microsoft Rich Edit 1.0 and later. For information about the compatibility of rich edit versions with the various system versions, see [About Rich Edit Controls](about-rich-edit-controls.md). Read more on docs.microsoft.com. Replaces the selected text in an edit control or a rich edit control with the specified text. This message does not return a value. Use the **EM\_REPLACESEL** message to replace only a portion of the text in an edit control. To replace all of the text, use the [**WM\_SETTEXT**](/windows/desktop/winmsg/wm-settext) message. If there is no selection, the replacement text is inserted at the caret. **Rich Edit:** Supported in Microsoft Rich Edit 1.0 and later. For information about the compatibility of rich edit versions with the various system versions, see [About Rich Edit Controls](about-rich-edit-controls.md). In a rich edit control, the replacement text takes the formatting of the character at the caret or, if there is a selection, of the first character in the selection. Read more on docs.microsoft.com. Copies a line of text from an edit control and places it in a specified buffer. You can send this message to either an edit control or a rich edit control. The return value is the number of **TCHAR**s copied. The return value is zero if the line number specified by the *wParam* parameter is greater than the number of lines in the edit control. **Edit controls:** The copied line does not contain a terminating null character. **Rich edit controls:** Supported in Microsoft Rich Edit 1.0 and later. The copied line does not contain a terminating null character, unless no text was copied. If no text was copied, the message places a null character at the beginning of the buffer. For information about the compatibility of rich edit versions with the various system versions, see [About Rich Edit Controls](about-rich-edit-controls.md). Read more on docs.microsoft.com. EM_LIMITTEXT message - Sets the text limit of an edit control. This message does not return a value. The **EM\_LIMITTEXT** message limits only the text the user can enter. It does not affect any text already in the edit control when the message is sent, nor does it affect the length of the text copied to the edit control by the [**WM\_SETTEXT**](/windows/desktop/winmsg/wm-settext) message. If an application uses the **WM\_SETTEXT** message to place more text into an edit control than is specified in the **EM\_LIMITTEXT** message, the user can edit the entire contents of the edit control. Before **EM\_LIMITTEXT** is called, the default limit for the amount of text a user can enter in an edit control is 32,767 characters. For single-line edit controls, the text limit is either 0x7FFFFFFE bytes or the value of the *wParam* parameter, whichever is smaller. For multiline edit controls, this value is either -1 byte or the value of the *wParam* parameter, whichever is smaller. **Rich Edit:** Supported in Microsoft Rich Edit 1.0 and later. Use the message [**EM\_EXLIMITTEXT**](em-exlimittext.md) for text length values greater than 64,000. For information about the compatibility of rich edit versions with the various system versions, see [About Rich Edit Controls](about-rich-edit-controls.md). Read more on docs.microsoft.com. Determines whether there are any actions in an edit control's undo queue. You can send this message to either an edit control or a rich edit control. If there are actions in the control's undo queue, the return value is nonzero. If the undo queue is empty, the return value is zero. If the undo queue is not empty, you can send the [**EM\_UNDO**](em-undo.md) message to the control to undo the most recent operation. **Edit controls and Rich Edit 1.0:** The undo queue contains only the most recent operation. **Rich Edit 2.0 and later:** The undo queue can contain multiple operations. **Rich Edit:** Supported in Microsoft Rich Edit 1.0 and later. For information about the compatibility of rich edit versions with the various system versions, see [About Rich Edit Controls](about-rich-edit-controls.md). Read more on docs.microsoft.com. This message undoes the last edit control operation in the control's undo queue. You can send this message to either an edit control or a rich edit control. For a single-line edit control, the return value is always **TRUE**. For a multiline edit control, the return value is **TRUE** if the undo operation is successful, or **FALSE** if the undo operation fails. **Edit controls and Rich Edit 1.0:** An undo operation can also be undone. For example, you can restore deleted text with the first **EM\_UNDO** message, and remove the text again with a second **EM\_UNDO** message as long as there is no intervening edit operation. **Rich Edit 2.0 and later:** The undo feature is multilevel so sending two **EM\_UNDO** messages will undo the last two operations in the undo queue. To redo an operation, send the [**EM\_REDO**](em-redo.md) message. **Rich Edit:** Supported in Microsoft Rich Edit 1.0 and later. For information about the compatibility of rich edit versions with the various system versions, see [About Rich Edit Controls](about-rich-edit-controls.md). Read more on docs.microsoft.com. Sets a flag that determines whether a multiline edit control includes soft line-break characters. A soft line break consists of two carriage returns and a line feed and is inserted at the end of a line that is broken because of wordwrapping. The return value is identical to the *wParam* parameter. This message affects only the buffer returned by the [**EM\_GETHANDLE**](em-gethandle.md) message and the text returned by the [**WM\_GETTEXT**](/windows/desktop/winmsg/wm-gettext) message. It has no effect on the display of the text within the edit control. The **EM\_FMTLINES** message does not affect a line that ends with a hard line break. A hard line break consists of one carriage return and a line feed. > [!Note] > The size of the text changes when this message is processed. **Rich Edit:** The **EM\_FMTLINES** message is not supported. Read more on docs.microsoft.com. Gets the index of the line that contains the specified character index in a multiline edit control. The return value is the zero-based line number of the line containing the character index specified by *wParam*. **Rich Edit:** Supported in Microsoft Rich Edit 1.0 and later. If the character index is greater than 64,000, use the [**EM\_EXLINEFROMCHAR**](em-exlinefromchar.md) message. For information about the compatibility of rich edit versions with the various system versions, see [About Rich Edit Controls](about-rich-edit-controls.md). The EM\_SETTABSTOPS message sets the tab stops in a multiline edit control. If all the tabs are set, the return value is **TRUE**. If all the tabs are not set, the return value is **FALSE**. The **EM\_SETTABSTOPS** message does not automatically redraw the edit control window. If the application is changing the tab stops for text already in the edit control, it should call the [**InvalidateRect**](/windows/desktop/api/winuser/nf-winuser-invalidaterect) function to redraw the edit control window. The values specified in the array are in dialog template units, which are the device-independent units used in dialog box templates. To convert measurements from dialog template units to screen units (pixels), use the [**MapDialogRect**](/windows/desktop/api/winuser/nf-winuser-mapdialogrect) function. **Rich Edit:** Supported in Microsoft Rich Edit 3.0 and later. A rich edit control can have the maximum number of tab stops specified by MAX\_TAB\_STOPS. For information about the compatibility of rich edit versions with the various system versions, see [About Rich Edit Controls](about-rich-edit-controls.md). Read more on docs.microsoft.com. Sets or removes the password character for an edit control. When a password character is set, that character is displayed in place of the characters typed by the user. You can send this message to either an edit control or a rich edit control. This message does not return a value. When an edit control receives the **EM\_SETPASSWORDCHAR** message, the control redraws all visible characters using the character specified by the *wParam* parameter. If *wParam* is zero, the control redraws all visible characters using the characters typed by the user. If an edit control is created with the [**ES\_PASSWORD**](edit-control-styles.md) style, the default password character is set to an asterisk (\*). If an edit control is created without the **ES\_PASSWORD** style, there is no password character. The **ES\_PASSWORD** style is removed if an **EM\_SETPASSWORDCHAR** message is sent with the *wParam* parameter set to zero. **Edit controls:** Multiline edit controls do not support the password style or messages. **Rich Edit:** Supported in Microsoft Rich Edit 2.0 and later. Both single-line and multiline edit controls support the password style and messages. For information about the compatibility of rich edit versions with the various system versions, see [About Rich Edit Controls](about-rich-edit-controls.md). Read more on docs.microsoft.com. Resets the undo flag of an edit control. The undo flag is set whenever an operation within the edit control can be undone. You can send this message to either an edit control or a rich edit control. This message does not return a value. The undo flag is automatically reset whenever the edit control receives a [**WM\_SETTEXT**](/windows/desktop/winmsg/wm-settext) or [**EM\_SETHANDLE**](em-sethandle.md) message. **Edit controls and Rich Edit 1.0:** The control can only undo or redo the most recent operation. **Rich Edit 2.0 and later:** The **EM\_EMPTYUNDOBUFFER** message empties all undo and redo buffers. Rich edit controls enable the user to undo or redo multiple operations. **Rich Edit:** Supported in Microsoft Rich Edit 1.0 and later. For information about the compatibility of rich edit versions with the various system versions, see [About Rich Edit Controls](about-rich-edit-controls.md). Read more on docs.microsoft.com. Gets the zero-based index of the uppermost visible line in a multiline edit control. You can send this message to either an edit control or a rich edit control. The return value is the zero-based index of the uppermost visible line in a multiline edit control. **Edit controls:** For single-line edit controls, the return value is the zero-based index of the first visible character. **Rich edit controls:** For single-line rich edit controls, the return value is zero. The number of lines and the length of the lines in an edit control depend on the width of the control and the current Wordwrap setting. **Rich Edit:** Supported in Microsoft Rich Edit 1.0 and later. For information about the compatibility of rich edit versions with the various system versions, see [About Rich Edit Controls](about-rich-edit-controls.md). Read more on docs.microsoft.com. Sets or removes the read-only style (ES\_READONLY) of an edit control. You can send this message to either an edit control or a rich edit control. If the operation succeeds, the return value is nonzero. If the operation fails, the return value is zero. When an edit control has the [**ES\_READONLY**](edit-control-styles.md) style, the user cannot change the text within the edit control. To determine whether an edit control has the [**ES\_READONLY**](edit-control-styles.md) style, use the [**GetWindowLong**](/windows/desktop/api/winuser/nf-winuser-getwindowlonga) function with the GWL\_STYLE flag. **Rich Edit:** Supported in Microsoft Rich Edit 1.0 and later. For information about the compatibility of rich edit versions with the various system versions, see [About Rich Edit Controls](about-rich-edit-controls.md). Read more on docs.microsoft.com. Replaces an edit control's default Wordwrap function with an application-defined Wordwrap function. You can send this message to either an edit control or a rich edit control. This message does not return a value. A Wordwrap function scans a text buffer that contains text to be sent to the screen, looking for the first word that does not fit on the current screen line. The Wordwrap function places this word at the beginning of the next line on the screen. A Wordwrap function defines the point at which the system should break a line of text for multiline edit controls, usually at a space character that separates two words. Either a multiline or a single-line edit control might call this function when the user presses arrow keys in combination with the CTRL key to move the caret to the next word or previous word. The default Wordwrap function breaks a line of text at a space character. The application-defined function may define the Wordwrap to occur at a hyphen or a character other than the space character. **Rich Edit:** Supported in Microsoft Rich Edit 1.0 and later. For information about the compatibility of rich edit versions with the various system versions, see [About Rich Edit Controls](about-rich-edit-controls.md). Read more on docs.microsoft.com. Gets the address of the current Wordwrap function. You can send this message to either an edit control or a rich edit control. The return value specifies the address of the application-defined Wordwrap function. The return value is **NULL** if no Wordwrap function exists. A Wordwrap function scans a text buffer that contains text to be sent to the display, looking for the first word that does not fit on the current display line. The wordwrap function places this word at the beginning of the next line on the display. A Wordwrap function defines the point at which the system should break a line of text for multiline edit controls, usually at a space character that separates two words. **Rich Edit:** Supported in Microsoft Rich Edit 1.0 and later. For information about the compatibility of rich edit versions with the various system versions, see [About Rich Edit Controls](about-rich-edit-controls.md). Read more on docs.microsoft.com. Gets the password character that an edit control displays when the user enters text. You can send this message to either an edit control or a rich edit control. The return value specifies the character to be displayed in place of any characters typed by the user. If the return value is **NULL**, there is no password character, and the control displays the characters typed by the user. If an edit control is created with the [**ES\_PASSWORD**](edit-control-styles.md) style, the default password character is set to an asterisk (\*). If an edit control is created without the **ES\_PASSWORD** style, there is no password character. To change the password character, send the [**EM\_SETPASSWORDCHAR**](em-setpasswordchar.md) message. **Edit controls:** Multiline edit controls do not support the password style or messages. **Rich edit:** Supported in Microsoft Rich Edit 2.0 and later. Both single-line and multiline edit controls support the password style and messages. For information about the compatibility of rich edit versions with the various system versions, see [About Rich Edit Controls](about-rich-edit-controls.md). Read more on docs.microsoft.com. Sets the widths of the left and right margins for an edit control. The message redraws the control to reflect the new margins. You can send this message to either an edit control or a rich edit control. This message does not return a value. **Edit controls:** You cannot use **EC\_USEFONTINFO** in the *wParam* parameter, but you can use it in the *lParam* parameter. **Rich Edit:** Supported in Microsoft Rich Edit 1.0 and later. All rich edit versions support the use of **EC\_USEFONTINFO** in the *wParam* parameter. However, only Microsoft Rich Edit 3.0 and later support the use of **EC\_USEFONTINFO** in the *lParam* parameter. For information about the compatibility of rich edit versions with the various system versions, see [About Rich Edit Controls](about-rich-edit-controls.md). Read more on docs.microsoft.com. Gets the widths of the left and right margins for an edit control. Returns the width of the left margin in the LOWORD, and the width of the right margin in the HIWORD. **Rich Edit:** The **EM\_GETMARGINS** message is not supported. Sets the status flags that determine how an edit control interacts with the Input Method Editor (IME). Returns the previous value of the *lParam* parameter. **Rich Edit:** The **EM\_SETIMESTATUS** message is not supported. Gets a set of status flags that indicate how the edit control interacts with the Input Method Editor (IME). Data specific to the type of status to retrieve. With the **EMSIS\_COMPOSITIONSTRING** value for *status*, this return value is one or more of the following values. | Return code | Description | |----------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |
**EIMES\_GETCOMPSTRATONCE**
| If this flag is set, the edit control hooks the [**WM\_IME\_COMPOSITION**](/windows/desktop/Intl/wm-ime-composition) message with *fFlags* set to GCS\_RESULTSTR and returns the result string immediately. If this flag is not set, the edit control passes the **WM\_IME\_COMPOSITION** message to the default window procedure and processes the result string from the [**WM\_CHAR**](/windows/desktop/inputdev/wm-char) message; this is the default behavior of the edit control.
| |
**EIMES\_CANCELCOMPSTRINFOCUS**
| If this flag is set, the edit control cancels the composition string when it receives the [**WM\_SETFOCUS**](/windows/desktop/inputdev/wm-setfocus) message. If this flag is not set, the edit control does not cancel the composition string; this is the default behavior of the edit control.
| |
**EIMES\_COMPLETECOMPSTRKILLFOCUS**
| If this flag is set, the edit control completes the composition string upon receiving the [**WM\_KILLFOCUS**](/windows/desktop/inputdev/wm-killfocus) message. If this flag is not set, the edit control does not complete the composition string; this is the default behavior of the edit control.
| **Rich Edit:** The **EM\_GETIMESTATUS** message is not supported. Determines whether a rich edit control can paste a specified clipboard format. If the clipboard format can be pasted, the return value is a nonzero value. If the clipboard format cannot be pasted, the return value is zero. Learn more about this API from docs.microsoft.com. Displays a portion of the contents of a rich edit control, as previously formatted for a device using the EM\_FORMATRANGE message. If the operation succeeds, the return value is **TRUE**. If the operation fails, the return value is **FALSE**. Text and Component Object Model (COM) objects are clipped by the rectangle. The application does not need to set the clipping region. Banding is the process by which a single page of output is generated using one or more separate rectangles, or bands. When all bands are placed on the page, a complete image results. This approach is often used by raster printers that do not have sufficient memory or ability to image a full page at one time. Banding devices include most dot matrix printers as well as some laser printers. Read more on docs.microsoft.com. Retrieves the starting and ending character positions of the selection in a rich edit control. This message does not return a value. Learn more about this API from docs.microsoft.com. Sets an upper limit to the amount of text the user can type or paste into a rich edit control. This message does not return a value. The text limit set by the **EM\_EXLIMITTEXT** message does not limit the amount of text that you can stream into a rich edit control using the [**EM\_STREAMIN**](em-streamin.md) message with *lParam* set to SF\_TEXT. However, it does limit the amount of text that you can stream into a rich edit control using the **EM\_STREAMIN** message with *lParam* set to SF\_RTF. Before **EM\_EXLIMITTEXT** is called, the default limit to the amount of text a user can enter is 32,767 characters. Read more on docs.microsoft.com. Determines which line contains the specified character in a rich edit control. This message returns the zero-based index of the line. Learn more about this API from docs.microsoft.com. Selects a range of characters or Component Object Model (COM) objects in a Microsoft Rich Edit control. The return value is the selection that is actually set. Learn more about this API from docs.microsoft.com. EM_FINDTEXT message - Finds text within a rich edit control. If the target string is found, the return value is the zero-based position of the first character of the match. If the target is not found, the return value is -1. The **cpMin** member of **FINDTEXT.chrg** always specifies the starting-point of the search, and **cpMax** specifies the end point. When searching backward, **cpMin** must be equal to or greater than **cpMax**. When searching forward, a value of -1 in **cpMax** extends the search range to the end of the text. Formats a range of text in a rich edit control for a specific device. This message returns the index of the last character that fits in the region, plus 1. This message is typically used to format the content of rich edit control for an output device such as a printer. After using this message to format a range of text, it is important that you free cached information by sending **EM\_FORMATRANGE** again, but with *lParam* set to **NULL**; otherwise, a memory leak will occur. Also, after using this message for one device, you must free cached information before using it again for a different device. Read more on docs.microsoft.com. Determines the character formatting in a rich edit control. This message returns the value of the **dwMask** member of the [**CHARFORMAT**](/windows/win32/api/richedit/ns-richedit-charformata) structure. Learn more about this API from docs.microsoft.com. Retrieves the event mask for a rich edit control. The event mask specifies which notification codes the control sends to its parent window. This message returns the event mask for the rich edit control. Learn more about this API from docs.microsoft.com. Retrieves an IRichEditOle object that a client can use to access a rich edit control's Component Object Model (COM) functionality. If the operation succeeds, the return value is a nonzero value. If the operation fails, the return value is zero. Learn more about this API from docs.microsoft.com. Retrieves the paragraph formatting of the current selection in a rich edit control. This message returns the value of the **dwMask** member of the [**PARAFORMAT**](/windows/desktop/api/Richedit/ns-richedit-paraformat) structure. Learn more about this API from docs.microsoft.com. Retrieves the currently selected text in a rich edit control. This message returns the number of characters copied, not including the terminating null character. Learn more about this API from docs.microsoft.com. The EM\_HIDESELECTION message hides or shows the selection in a rich edit control. This message does not return a value. Learn more about this API from docs.microsoft.com. Pastes a specific clipboard format in a rich edit control. This message does not return a value. Learn more about this API from docs.microsoft.com. Forces a rich edit control to send an EN\_REQUESTRESIZE notification code to its parent window. This message does not return a value. This message is useful during [**WM\_SIZE**](/windows/desktop/winmsg/wm-size) processing for the parent of a bottomless rich edit control. Determines the selection type for a rich edit control. If the selection is empty, the return value is SEL\_EMPTY. If the selection is not empty, the return value is a set of flags containing one or more of the following values. | Return code | Description | |-------------------------------------------------------------------------------------------------|---------------------------------------------| |
**SEL\_TEXT**
| Text.
| |
**SEL\_OBJECT**
| At least one COM object.
| |
**SEL\_MULTICHAR**
| More than one character of text.
| |
**SEL\_MULTIOBJECT**
| More than one COM object.
| This message is useful during [**WM\_SIZE**](/windows/desktop/winmsg/wm-size) processing for the parent of a bottomless rich edit control. The EM\_SETBKGNDCOLOR message sets the background color for a rich edit control. This message returns the original background color. Learn more about this API from docs.microsoft.com. Sets character formatting in a rich edit control. If the operation succeeds, the return value is a nonzero value. If the operation fails, the return value is zero. If this message is sent more than once with the same parameters, the effect on the text is toggled. That is, sending the message once produces the effect, sending the message twice cancels the effect, and so forth. Sets the event mask for a rich edit control. The event mask specifies which notification codes the control sends to its parent window. This message returns the previous event mask. The default event mask (before any is set) is ENM\_NONE. Gives a rich edit control an IRichEditOleCallback object that the control uses to get OLE-related resources and information from the client. If the operation succeeds, the return value is a nonzero value. If the operation fails, the return value is zero. Learn more about this API from docs.microsoft.com. Sets the paragraph formatting for the current selection in a rich edit control. If the operation succeeds, the return value is a nonzero value. If the operation fails, the return value is zero. Learn more about this API from docs.microsoft.com. Sets the target device and line width used for \ 0034;what you see is what you get \ 0034; (WYSIWYG) formatting in a rich edit control. The return value is zero if the operation fails, or nonzero if it succeeds. The HDC for the default printer can be obtained as follows. This doc was truncated. Read more on docs.microsoft.com. Replaces the contents of a rich edit control with a stream of data provided by an application defined \ 8211;EditStreamCallback callback function. This message returns the number of characters read. When you send an **EM\_STREAMIN** message, the rich edit control makes repeated calls to the [*EditStreamCallback*](/windows/desktop/api/Richedit/nc-richedit-editstreamcallback) function specified by the **pfnCallback** member of the [**EDITSTREAM**](/windows/desktop/api/Richedit/ns-richedit-editstream) structure. Each time the callback function is called, it fills a buffer with data to read into the control. This continues until the callback function indicates that the stream-in operation has been completed or an error occurs. Causes a rich edit control to pass its contents to an application \ 8211;defined EditStreamCallback callback function. The callback function can then write the stream of data to a file or any other location that it chooses. This message returns the number of characters written to the data stream. When you send an **EM\_STREAMOUT** message, the rich edit control makes repeated calls to the [*EditStreamCallback*](/windows/desktop/api/Richedit/nc-richedit-editstreamcallback) function specified by the **pfnCallback** member of the [**EDITSTREAM**](/windows/desktop/api/Richedit/ns-richedit-editstream) structure. Each time it calls the callback function, the control passes a buffer containing a portion of the contents of the control. This process continues until the control has passed all its contents to the callback function, or until an error occurs. Retrieves a specified range of characters from a rich edit control. The message returns the number of characters copied, not including the terminating null character. Learn more about this API from docs.microsoft.com. Finds the next word break before or after the specified character position or retrieves information about the character at that position. The message returns a value based on the *wParam* parameter. | Return code | Description | |------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------| |
**wParam**
| Return Value
| |
**WB\_CLASSIFY**
| Returns the character class and word-break flags of the character at the specified position.
| |
**WB\_ISDELIMITER**
| Returns **TRUE** if the character at the specified position is a delimiter; otherwise it returns **FALSE**.
| |
**Others**
| Returns the character index of the word break.
| If *wParam* is WB\_LEFT and WB\_RIGHT, the word-break procedure finds word breaks only after delimiters. This matches the functionality of an edit control. If *wParam* is WB\_MOVEWORDLEFT or WB\_MOVEWORDRIGHT, the word-break procedure also compares character classes and word-break flags. For information about character classes and word-break flags, see [Word and Line Breaks](using-rich-edit-controls.md). Read more on docs.microsoft.com. Sets the options for a rich edit control. This message returns the current options of the edit control. Learn more about this API from docs.microsoft.com. Retrieves rich edit control options. This message returns a combination of the current option flag values described in the [**EM\_SETOPTIONS**](em-setoptions.md) message. Learn more about this API from docs.microsoft.com. EM_FINDTEXTEX message - Finds text within a rich edit control. If the target string is found, the return value is the zero-based position of the first character of the match. If the target is not found, the return value is -1. Use this message to find ANSI strings. For Unicode, use [**EM\_FINDTEXTEXW**](em-findtextexw.md). The **cpMin** member of **FINDTEXTEX.chrg** always specifies the starting-point of the search, and **cpMax** specifies the end point. When searching backward, **cpMin** must be equal to or greater than **cpMax**. When searching forward, a value of -1 in **cpMax** extends the search range to the end of the text. If the search operation finds a match, the **chrgText** member of the [**FINDTEXTEX**](/windows/desktop/api/Richedit/ns-richedit-findtextexa) structure returns the range of character positions that contains the matching text. Read more on docs.microsoft.com. Retrieves the address of the currently registered extended word-break procedure for a rich edit control. The message returns the address of the current procedure. Learn more about this API from docs.microsoft.com. Sets the extended word-break procedure for a rich edit control. This message returns the address of the previous extended word-break procedure. Learn more about this API from docs.microsoft.com. Sets the maximum number of actions that can stored in the undo queue of a rich edit control. The return value is the new maximum number of undo actions for the rich edit control. This value may be less than *wParam* if memory is limited. By default, the maximum number of actions in the undo queue is 100. If you increase this number, there must be enough available memory to accommodate the new number. For better performance, set the limit to the smallest possible value. Setting the limit to zero disables the **Undo** feature. Read more on docs.microsoft.com. Sends an EM\_REDO message to a rich edit control to redo the next action in the control's redo queue. If the **Redo** operation succeeds, the return value is a nonzero value. If the **Redo** operation fails, the return value is zero. To determine whether there are any actions in the control's redo queue, send the [**EM\_CANREDO**](em-canredo.md) message. Determines whether there are any actions in the control redo queue. If there are actions in the control redo queue, the return value is a nonzero value. If the redo queue is empty, the return value is zero. To redo the most recent undo operation, send the [**EM\_REDO**](em-redo.md) message. Microsoft Rich Edit 2.0 and later Retrieves the type of the next undo action, if any.Microsoft Rich Edit 1.0 This message is not supported. If there is an undo action, the value returned is an [**UNDONAMEID**](/windows/desktop/api/Richedit/ne-richedit-undonameid) enumeration value that indicates the type of the next action in the control's undo queue. If there are no actions that can be undone or the type of the next undo action is unknown, the return value is zero. The types of actions that can be undone or redone include typing, delete, drag, drop, cut, and paste operations. This information can be useful for applications that provide an extended user interface for undo and redo operations, such as a drop-down list box of actions that can be undone. Retrieves the type of the next action, if any, in the rich edit control's redo queue. If the redo queue for the control is not empty, the value returned is an [**UNDONAMEID**](/windows/desktop/api/Richedit/ne-richedit-undonameid) enumeration value that indicates the type of the next action in the control's redo queue. If there are no redoable actions or the type of the next redoable action is unknown, the return value is zero. The types of actions that can be undone or redone include typing, delete, drag-drop, cut, and paste operations. This information can be useful for applications that provide an extended user interface for undo and redo operations, such as a drop-down list box of redoable actions. Stops a rich edit control from collecting additional typing actions into the current undo action. The control stores the next typing action, if any, into a new action in the undo queue. The return value is zero. This message cannot fail. A rich edit control groups consecutive typing actions, including characters deleted by using the **BackSpace** key, into a single undo action until one of the following events occurs: - The control receives an **EM\_STOPGROUPTYPING** message. - The control loses focus. - The user moves the current selection, either by using the arrow keys or by clicking the mouse. - The user presses the **Delete** key. - The user performs any other action, such as a paste operation that does **not** involve typing. You can send the **EM\_STOPGROUPTYPING** message to break consecutive typing actions into smaller undo groups. For example, you could send **EM\_STOPGROUPTYPING** after each character or at each word break. Read more on docs.microsoft.com. Sets the text mode or undo level of a rich edit control. The message fails if the control contains any text. If the message succeeds, the return value is zero. If the message fails, the return value is a nonzero value. In rich text mode, a rich edit control has standard rich edit functionality. However, in plain text mode, the control is similar to a standard edit control: - The text in a plain text control can have only one format (such as Bold, 10pt Arial). - The user cannot paste rich text formats, such as Rich Text Format (RTF) or embedded objects into a plain text control. - Rich text mode controls always have a default end-of-document marker or carriage return, to format paragraphs. Plain text controls, on the other hand, do not need the default, end-of-document marker, so it is omitted. The control must contain no text when it receives the **EM\_SETTEXTMODE** message. To ensure there is no text, send a [**WM\_SETTEXT**](/windows/desktop/winmsg/wm-settext) message with an empty string (""). Read more on docs.microsoft.com. Gets the current text mode and undo level of a rich edit control. The return value is one or more values from the [**TEXTMODE**](/windows/win32/api/richedit/ne-richedit-textmode) enumeration type. The values indicate the current text mode and undo level of the control. Learn more about this API from docs.microsoft.com. Enables or disables automatic detection of hyperlinks by a rich edit control. If the message succeeds, the return value is zero. If the message fails, the return value is a nonzero value. For example, the message might fail due to insufficient memory, an invalid detection option, or an invalid scheme-name string. If *lParam* contains more than 50 scheme names, the message fails with a return value of **E\_INVALIDARG**. If automatic URL detection is enabled (that is, *wParam* includes **AURL\_ENABLEURL**), the rich edit control scans any modified text to determine whether the text matches the format of a URL (or more generally in Windows 8 or later an IRI International Resource Identifier). If *lParam* is NULL, the control detects URLs that begin with the following scheme names: - callto - file - ftp - gopher - http - https - mailto - news - notes - nntp - onenote - outlook - prospero - tel - telnet - wais - webcal When automatic link detection is enabled, the rich edit control removes the **CFE\_LINK** effect from modified text that does not have a format recognized by the control. If your application uses the **CFE\_LINK** effect to mark other types of text, do not enable automatic link detection. The rich edit control does not check whether a detected link exists; that responsibility belongs to the client. A rich edit control sends the [EN\_LINK](en-link.md) notification when it receives various messages while the mouse pointer is over text that has the **CFE\_LINK** effect. For more information, see [Automatic RichEdit Hyperlinks](/archive/blogs/murrays/automatic-richedit-hyperlinks) and [RichEdit Friendly Name Hyperlinks](/archive/blogs/murrays/richedit-friendly-name-hyperlinks). Read more on docs.microsoft.com. Indicates whether the auto URL detection is turned on in the rich edit control. If auto-URL detection is active, the return value is 1. If auto-URL detection is inactive, the return value is 0. When auto URL detection is on, Microsoft Rich Edit is constantly checking typed text for a valid URL. Rich Edit recognizes URLs that start with these prefixes: - http: - file: - mailto: - ftp: - https: - gopher: - nntp: - prospero: - telnet: - news: - wais: - outlook: Rich Edit also recognizes standard path names that start with \\\\. When Rich Edit locates a URL, it changes the URL text color, underlines the text, and notifies the client using [EN\_LINK](en-link.md). Read more on docs.microsoft.com. Changes the palette that a rich edit control uses for its display window. This message does not return a value. The rich edit control does not check whether the new palette is valid. Gets the text from a rich edit control. The return value is the number of **TCHAR**s copied into the output buffer, not including the null terminator. If the size of the output buffer is less than the size of the text in the control, the edit control will copy text from its beginning and place it in the buffer until the buffer is full. A terminating null character will still be placed at the end of the buffer. If ANSI text is requested, **EM\_GETTEXTEX** uses the [**WideCharToMultiByte**](/windows/desktop/api/stringapiset/nf-stringapiset-widechartomultibyte) function to translate the Unicode characters to ANSI. It allows you to go from Unicode to ANSI using a particular code page. The [**GETTEXTEX**](/windows/desktop/api/Richedit/ns-richedit-gettextex) structure contains members (**lpDefaultChar** and **lpUsedDefChar**) that are used in the translation from Unicode to ANSI. Read more on docs.microsoft.com. Calculates text length in various ways. It is usually called before creating a buffer to receive the text from the control. The message returns the number of **TCHAR**s in the edit control, depending on the setting of the flags in the [**GETTEXTLENGTHEX**](/windows/desktop/api/Richedit/ns-richedit-gettextlengthex) structure. If incompatible flags were set in the **flags** member, the message returns E\_INVALIDARG . This message is a fast and easy way to determine the number of characters in the Unicode version of the rich edit control. However, for a non-Unicode target code page you will potentially be converting to a combination of single-byte and double-byte characters. Shows or hides one of the scroll bars in the host window of a rich edit control. This message does not return a value. This method is only valid when the control is in-place active. Calls made while the control is inactive may fail. Combines the functionality of the WM\_SETTEXT and EM\_REPLACESEL messages, and adds the ability to set text using a code page and to use either rich text or plain text. If the operation is setting all of the text and succeeds, the return value is 1. If the operation is setting the selection and succeeds, the return value is the number of bytes or characters copied. If the operation fails, the return value is zero. Learn more about this API from docs.microsoft.com. Sets the punctuation characters for a rich edit control. If the operation succeeds, the return value is a nonzero value. If the operation fails, the return value is zero. Learn more about this API from docs.microsoft.com. Gets the current punctuation characters for the rich edit control. If the operation succeeds, the return value is a nonzero value. If the operation fails, the return value is zero. Learn more about this API from docs.microsoft.com. Sets the word-wrapping and word-breaking options for a rich edit control. This message returns the current word-wrapping and word-breaking options. This message must not be sent by the application defined word breaking procedure. Gets the current word wrap and word-break options for the rich edit control. The message returns the current word wrap and word-break options. This message must not be sent by the application-defined, word-break procedure. Sets the Input Method Editor (IME) composition color for a rich edit control. If the operation succeeds, the return value is a nonzero value. If the operation fails, the return value is zero. Learn more about this API from docs.microsoft.com. Retrieves the Input Method Editor (IME) composition color. If the operation succeeds, the return value is a nonzero value. If the operation fails, the return value is zero. Learn more about this API from docs.microsoft.com. Sets the Input Method Editor (IME) options. If the operation succeeds, the return value is a nonzero value. If the operation fails, the return value is zero. Learn more about this API from docs.microsoft.com. Retrieves the current Input Method Editor (IME) options. This message returns one or more of the IME option flag values described in the [**EM\_SETIMEOPTIONS**](em-setimeoptions.md) message. Learn more about this API from docs.microsoft.com. EM_CONVPOSITION message Learn more about this API from docs.microsoft.com. Sets options for Input Method Editor (IME) and Asian language support in a rich edit control. This message returns a value of 1. The **EM\_SETLANGOPTIONS** message controls the following: - Automatic font binding. - Automatic keyboard switching. - Automatic font size adjustment. - Use of user-interface default fonts instead of document default fonts. - Notifications to client during IME composition. - How IME aborts composition mode. - Spell checking, autocorrect, and touch keyboard prediction. This message sets the values of all language option flags. To change a subset of the flags, send the [**EM\_GETLANGOPTIONS**](em-getlangoptions.md) message to get the current option flags, change the flags that you need to change, and then send the **EM\_SETLANGOPTIONS** message with the result. Read more on docs.microsoft.com. Gets a rich edit control's option settings for Input Method Editor (IME) and Asian language support. Returns the IME and Asian language settings, which can be zero or more of the following values. | Return code | Description | |-----------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |
**IMF\_AUTOFONT**
| If this flag is set, the control automatically changes fonts when the user explicitly changes to a different keyboard layout. It is useful to turn off **IMF\_AUTOFONT** for universal Unicode fonts. This option is turned on by default (1).
| |
**IMF\_AUTOFONTSIZEADJUST**
| If this flag is set, the control scales font-bound font sizes from insertion point size according to script. For example, Asian fonts are slightly larger than Western ones. This option is turned on by default (1).
| |
**IMF\_AUTOKEYBOARD**
| If this flag is set, the control automatically changes the keyboard layout when the user explicitly changes to a different font, or when the user explicitly changes the insertion point to a new location in the text. Will be turned on automatically for bidirectional controls. For all other controls, it is turned off by default. This option is turned off by default (0).
| |
**IMF\_DISABLEAUTOBIDIAUTOKEYBOARD**
| **Windows 8**: If this flag is set, the control uses language neutral logic for automatic keyboard switching. This option is turned off by default (0).
| |
**IMF\_DUALFONT**
| If this flag is set, the control uses dual-font mode. Used for Asian language support. The control uses an English font for ASCII text and a Asian font for Asian text. This option is turned on by default (1).
| |
**IMF\_IMEALWAYSSENDNOTIFY**
| This flag controls how the rich edit control notifies the client during IME composition:
0: No [EN\_CHANGE](en-change.md) or [EN\_SELCHANGE](en-selchange.md) notifications during undetermined state. Send notification when the final string comes in. This is the default.
1: Send [EN\_CHANGE](en-change.md) and [EN\_SELCHANGE](en-selchange.md) events during undetermined state.
| |
**IMF\_IMECANCELCOMPLETE**
| This flag determines how the control uses the composition string of an IME if the user cancels it. If this flag is set, the control discards the composition string. If this flag is not set, the control uses the composition string as the result string. This option is turned off by default (0).
| |
**IMF\_NOIMPLICITLANG**
| **Windows 8**: If this flag is set, disable stamping keyboard input with the keyboard language and ensuring that non-East Asian language IDss are compatible with the character repertoire. This option is turned off by default (0).
| |
**IMF\_NOKBDLIDFIXUP**
| **Windows 8**: If this flag is set, the rich edit control disables stamping keyboard language on an empty control. This option is turned off by default (0).
| |
**IMF\_SPELLCHECKING**
| **Windows 8**: If this flag is set, the rich edit control turns on spell checking. This option is turned off by default (0).
| |
**IMF\_TKBAUTOCORRECTION**
| **Windows 8**: If this flag is set, enable touch keyboard autocorrect. This option is turned off by default (0).
| |
**IMF\_TKBPREDICTION**
| **Windows 10**: Ignored.
**Windows 8**: If this flag is set, the rich edit control enables touch keyboard prediction. This option is turned off by default (0).
| |
**IMF\_UIFONTS**
| Use user-interface default fonts. This option is turned off by default (0).
| The **IMF\_AUTOFONT** flag is set by default. The **IMF\_AUTOKEYBOARD** and **IMF\_IMECANCELCOMPLETE** flags are cleared by default. Retrieves the current Input Method Editor (IME) mode for a rich edit control. The return value is one of the following values. | Return code | Description | |-------------------------------------------------------------------------------------------------|------------------------------| |
**ICM\_NOTOPEN**
| IME is not open.
| |
**ICM\_LEVEL3**
| True inline mode.
| |
**ICM\_LEVEL2**
| Level 2.
| |
**ICM\_LEVEL2\_5**
| Level 2.5
| |
**ICM\_LEVEL2\_SUI**
| Special UI.
| Learn more about this API from docs.microsoft.com. EM_FINDTEXTW message - Finds Unicode text within a rich edit control. If the target string is found, the return value is the zero-based position of the first character of the match. If the target is not found, the return value is -1. **EM\_FINDTEXTW** uses the [**FINDTEXTW**](/windows/win32/api/richedit/ns-richedit-findtexta) structure, while [**EM\_FINDTEXTEXW**](em-findtextexw.md) uses the [**FINDTEXTEXW**](/windows/desktop/api/Richedit/ns-richedit-findtextexa) structure. The difference is that **FINDTEXTEXW** reports back the range of text that was found. EM_FINDTEXTEXW message - Finds Unicode text within a rich edit control. If the target string is found, the return value is the zero-based position of the first character of the match. If the target is not found, the return value is -1. Use this message to find Unicode strings. For ANSI;, use [**EM\_FINDTEXTEX**](em-findtextex.md). The **cpMin** member of **FINDTEXTEX.chrg** always specifies the starting-point of the search, and **cpMax** specifies the end point. When searching backward, **cpMin** must be equal to or greater than **cpMax**. When searching forward, a value of -1 in **cpMax** extends the search range to the end of the text. If the search operation finds a match, the **chrgText** member of the [**FINDTEXTEX**](/windows/desktop/api/Richedit/ns-richedit-findtextexa) structure returns the range of character positions that contains the matching text. **EM\_FINDTEXTEXW** uses the [**FINDTEXTEXW**](/windows/desktop/api/Richedit/ns-richedit-findtextexa) structure, while [**EM\_FINDTEXTW**](em-findtextw.md) uses the [**FINDTEXTW**](/windows/win32/api/richedit/ns-richedit-findtexta) structure. The difference is that **EM\_FINDTEXTEXW** reports the range of text that was found. Read more on docs.microsoft.com. Invokes the Input Method Editor (IME) reconversion dialog box. This message always returns zero. Learn more about this API from docs.microsoft.com. Set the Input Method Editor (IME) mode bias for a rich edit control. This message returns the new IME mode bias setting. When the IME generates a list of alternative choices for a set of characters, this message sets the criteria by which some of the choices will appear at the top of the list. To set the Text Services Framework (TSF) mode bias, use [**EM\_SETCTFMODEBIAS**](em-setctfmodebias.md). The application should call [**EM\_ISIME**](em-isime.md) before calling this function. Read more on docs.microsoft.com. Retrieves the Input Method Editor (IME) mode bias for a Microsoft Rich Edit control. This message returns the current IME mode bias setting. To get the Text Services Framework mode bias, use [**EM\_GETCTFMODEBIAS**](em-getctfmodebias.md). The application should call [**EM\_ISIME**](em-isime.md) before calling this function. Read more on docs.microsoft.com. The EM\_SETBIDIOPTIONS message sets the current state of the bidirectional options in the rich edit control. This message does not return a value. The rich edit control must be in plain text mode or **EM\_SETBIDIOPTIONS** will not do anything. In plain text controls, **EM\_SETBIDIOPTIONS** automatically determines the paragraph direction and/or alignment based on the context rules. These rules state that the direction and/or alignment is derived from the first strong character in the control. A strong character is one from which text direction can be determined (see Unicode Standard version 2.0). The paragraph direction and/or alignment is applied to the default format. **EM\_SETBIDIOPTIONS** only switches the default paragraph format to RTL (right to left) if it finds an RTL character, Read more on docs.microsoft.com. Indicates the current state of the bidirectional options in the rich edit control. This message does not return a value. This message sets the values of the **wMask** and **wEffects** members to the value of the current state of the bidirectional options in the rich edit control. Sets the current state of the typography options of a rich edit control. Returns **TRUE** if *wParam* is valid, otherwise **FALSE**. Advanced line breaking is turned on automatically by the rich edit control when needed, such as for handling complex scripts like Arabic and Hebrew, and for mathematics. It s also needed for justified paragraphs, hyphenation, and other typographic features. Returns the current state of the typography options of a rich edit control. Returns the current typography options. For a list of options, see [**EM\_SETTYPOGRAPHYOPTIONS**](em-settypographyoptions.md). You can turn on advanced line breaking by sending the [**EM\_SETTYPOGRAPHYOPTIONS**](em-settypographyoptions.md) message. Advanced and normal line breaking may also be turned on automatically by the rich edit control if it is needed for certain languages. Sets the current edit style flags for a rich edit control. The return value is the state of the edit style flags after the rich edit control has attempted to implement your edit style changes. The edit style flags are a set of flags that indicate the current edit style. Learn more about this API from docs.microsoft.com. Retrieves the current edit style flags. Returns the current edit style flags, which can include one or more of the following values: | Return code | Description | |-------------|-------------| |
SES_BEEPONMAXTEXT
| Rich Edit will call the system beeper if the user attempts to enter more than the maximum characters.
| |
SES_BIDI
| Turns on bidirectional processing. This is automatically turned on by Rich Edit if any of the following window styles are active: WS_EX_RIGHT, WS_EX_RTLREADING, WS_EX_LEFTSCROLLBAR. However, this setting is useful for handling these window styles when using a custom implementation of ITextHost (default: 0).
| |
SES_CTFALLOWEMBED
| Windows XP with SP1: Allow embedded objects to be inserted using TSF (default: 0).
| |
SES_CTFALLOWPROOFING
| Windows XP with SP1: Allows TSF proofing tips (default: 0).
| |
SES_CTFALLOWSMARTTAG
| Windows XP with SP1: Allows TSF SmartTag tips (default: 0).
| |
SES_CTFNOLOCK
| Windows 8: Do not allow the TSF lock read/write access. This pauses TSF input.
| |
SES_DEFAULTLATINLIGA
| Windows 8: Fonts with an fi ligature are displayed with default OpenType features resulting in improved typography (default: 0).
| |
SES_DRAFTMODE
| Windows XP with SP1: Use draft mode fonts to display text. Draft mode is an accessibility option where the control displays the text with a single font; the font is determined by the system setting for the font used in message boxes. For example, accessible users may read text easier if it is uniform, rather than a mix of fonts and styles (default: 0).
| |
SES_EMULATE10
| Windows 8: Emulate RichEdit 1.0 behavior.
[!Note]
If you really want this behavior, use the Windows riched32.dll instead of riched20.dll or msftedit.dll. Riched32.dll had more functionality.

| |
SES_EMULATESYSEDIT
| When this bit is on, rich edit attempts to emulate the system edit control (default: 0).
| |
SES_EXTENDBACKCOLOR
| Extends the background color all the way to the edges of the client rectangle (default: 0).
| |
SES_HIDEGRIDLINES
| Windows XP with SP1: If the width of table gridlines is zero, gridlines are not displayed. This is equivalent to the hide gridlines feature in Word's table menu (default: 0).
| |
SES_HYPERLINKTOOLTIPS
| Windows 8: When the cursor is over a link, display a tooltip with the target link address (default: 0).
| |
SES_LOGICALCARET
| Windows 8: Provide logical caret information instead of a caret bitmap as described in ITextHost::TxSetCaretPos (default: 0).
| |
SES_LOWERCASE
| Converts all input characters to lowercase (default: 0).
| |
SES_MAPCPS
| Obsolete. Do not use.
| |
SES_MULTISELECT
| Windows 8: Enable multiselection with individual mouse selections made while the Ctrl key is pressed (default: 0).
| |
SES_NOEALINEHEIGHTADJUST
| Windows 8: Do not adjust line height for East Asian text (default: 0 which adjusts the line height by 15%).
| |
SES_NOFOCUSLINKNOTIFY
| Sends EN_LINK notification from links that do not have focus.
| |
SES_NOIME
| Disallows IMEs for this instance of the rich edit control (default: 0).
| |
SES_NOINPUTSEQUENCECHK
| When this bit is on, rich edit does not verify the sequence of typed text. Some languages (such as Thai and Vietnamese) require verifying the input sequence order before submitting it to the backing store (default: 0).
| |
SES_SCROLLONKILLFOCUS
| When KillFocus occurs, scroll to the beginning of the text (character position equal to 0) (default: 0).
| |
SES_SMARTDRAGDROP
| Windows 8: Add or delete a space according to the context when dropping text (default: 0).
| |
SES_USECRLF
| Obsolete. Do not use.
| |
SES_WORDDRAGDROP
| Windows 8: If word select is active, ensure that the drop location is at a word boundary (default: 0).
| |
SES_UPPERCASE
| Converts all input characters to uppercase (default: 0).
| |
SES_USEAIMM
| Uses the Active IMM input method component that ships with Internet Explorer 4.0 or later (default: 0).
| |
SES_USEATFONT
| Windows XP with SP1: Uses an @ font, which is designed for vertical text; this is used with the ES_VERTICAL window style. The name of an @ font begins with the @ symbol, for example, "@Batang" (default: 0, but is automatically turned on for vertical text layout).
| |
SES_USECTF
| Windows XP with SP1: Turns on TSF support. (default: 0)
| |
SES_XLTCRCRLFTOCR
| Turns on translation of CRCRLFs to CRs. When this bit is on and a file is read in, all instances of CRCRLF will be converted to hard CRs internally. This will affect the text wrapping. Note that if such a file is saved as plain text, the CRs will be replaced by CRLFs. This is the .txt standard for plain text (default: 0, which deletes CRCRLFs on input).
| Learn more about this API from docs.microsoft.com. Obtains the current scroll position of the edit control. This message always returns 1. The values returned in the [**POINT**](/windows/win32/api/windef/ns-windef-point) structure are 16-bit values (even in the 32-bit wide fields). Scrolls the contents of a rich edit control to the specified point. This message always returns 1. Learn more about this API from docs.microsoft.com. Gets the current zoom ratio. The zoom ration is always between 1/64 and 64. You can send this message to either an edit control or a rich edit control. The message returns **TRUE** if message is processed, which it will be if both *wParam* and *lParam* are not **NULL**. **Edit:** Supported in Windows 10 1809 and later. The edit control needs to have the **ES\_EX\_ZOOMABLE** extended style set, for this message to have an effect, see [Edit Control Extended Styles](edit-control-window-extended-styles.md). For information about the edit control, see [Edit Controls](edit-controls.md). Sets the zoom ratio. The ratio must be a value between 1/64 and 64. You can send this message to either an edit control or a rich edit control. If the new zoom setting is accepted, the return value is **TRUE**. If the new zoom setting is not accepted, the return value is **FALSE**. **Edit:** Supported in Windows 10 1809 and later. The edit control needs to have the **ES\_EX\_ZOOMABLE** extended style set, for this message to have an effect, see [Edit Control Extended Styles](edit-control-window-extended-styles.md). For information about the edit control, see [Edit Controls](about-edit-controls.md). Retrieves information about hyphenation for a Microsoft Rich Edit control. Learn more about this API from docs.microsoft.com. Sets the way a rich edit control does hyphenation. > [!Note] > To enable hyphenation, the client must call [**EM\_SETTYPOGRAPHYOPTIONS**](em-settypographyoptions.md), specifying TO\_ADVANCEDTYPOGRAPHY. Read more on docs.microsoft.com. Gets the text layout for a Microsoft Rich Edit control. Gets the current text layout. For a list of possible text layout values, see [**EM\_SETPAGEROTATE**](em-setpagerotate.md). Learn more about this API from docs.microsoft.com. Sets the text layout for a rich edit control. Return value is the new text layout value. This message sets the text layout for the entire document. However, embedded contents are not rotated and must be rotated separately by the application. Gets the Text Services Framework mode bias values for a Microsoft Rich Edit control. The current Text Services Framework mode bias value. To get the IME mode bias, call [**EM\_GETIMEMODEBIAS**](em-getimemodebias.md). Sets the Text Services Framework (TSF) mode bias for a rich edit control. If successful, the return value is the new TSF mode bias value. If unsuccessful, the return value is the old TSF mode bias value. When a Microsoft Rich Edit application uses TSF, it can select the TSF mode bias. This message sets the criteria by which an alternative choice appears at the top of the list for selection. To set the mode bias for the Input Method Editor (IME), use [**EM\_SETIMEMODEBIAS**](em-setimemodebias.md). Read more on docs.microsoft.com. Determines if the Text Services Framework (TSF) keyboard is open or closed. If the TSF keyboard is open, the return value is **TRUE**. Otherwise, it is **FALSE**. Learn more about this API from docs.microsoft.com. Opens or closes the Text Services Framework (TSF) keyboard. If successful, this message returns **TRUE**. If unsuccessful, this message returns **FALSE**. Learn more about this API from docs.microsoft.com. Retrieves the Input Method Editor (IME) composition text. If successful, the return value is the number of Unicode characters copied to the buffer. Otherwise, it is zero. This message only takes Unicode strings. **Security Warning:** Be sure to have a buffer sufficient for the size of the input. Failure to do so could cause problems for your application. Read more on docs.microsoft.com. Determine with a rich edit control's current input locale is an East Asian locale. Returns **TRUE** if it is an East Asian locale. Otherwise, it returns **FALSE**. Learn more about this API from docs.microsoft.com. Retrieves the property and capabilities of the Input Method Editor (IME) associated with the current input locale. Returns the property or capability value, depending on the value of the *lParam* parameter. For more information, see the Remarks. If *wParam* is IGP\_PROPERTY, it returns one or more of the following values. | Requirement | Value | |-------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | IME\_PROP\_AT\_CARET | If set, conversion window is at the caret position. If clear, the window is near caret position. | | IME\_PROP\_SPECIAL\_UI | If set, IME has a nonstandard user interface. The application should not draw in the IME window. | | IME\_PROP\_CANDLIST\_START\_FROM\_1 | If set, strings in the candidate list are numbered starting at 1. If clear, strings start at zero. | | IME\_PROP\_UNICODE | If set, the IME is viewed as a UnicodeIME. The system and the IME will communicate through the UnicodeIME interface. If clear, IME will use the ANSI interface to communicate with the system. | | IME\_PROP\_COMPLETE\_ON\_UNSELECT | If set, conversion window is at the caret position. If clear, the window is near caret position. | | IME\_PROP\_ACCEPT\_WIDE\_VKEY | If set, the IME processes the injected Unicode that came from the [**SendInput**](/windows/desktop/api/winuser/nf-winuser-sendinput) function by using VK\_PACKET. If clear, the IME might not process the injected Unicode, and the injected Unicode might be sent to the application directly. | If *wParam* is IGP\_UI, it returns one or more of the following values. | Requirement | Value | |-----------------|-------------------------------------------------------------------------------------------------------| | UI\_CAP\_2700 | Supports text escapement values of 0 or 2700. For more information, see **lfEscapement**. | | UI\_CAP\_ROT90 | Supports text escapement values of 0, 900, 1800, or 2700. For more information, see **lfEscapement**. | | UI\_CAP\_ROTANY | Supports any text escapement value. For more information, see **lfEscapement**. | If *wParam* is IGP\_SETCOMPSTR, it returns one or more of the following values. | Requirement | Value | |------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | SCS\_CAP\_COMPSTR | Can create the composition string by calling the [**ImmSetCompositionString**](/windows/desktop/api/imm/nf-imm-immsetcompositionstringa) function with the SCS\_SETSTR value. | | SCS\_CAP\_MAKEREAD | Can create the reading string from corresponding composition string when using the [**ImmSetCompositionString**](/windows/desktop/api/imm/nf-imm-immsetcompositionstringa) function with SCS\_SETSTR and without setting *lpRead*. | | SCS\_CAP\_SETRECONVERTSTRING | This IME can support reconversion. Use [**ImmSetCompositionString**](/windows/desktop/api/imm/nf-imm-immsetcompositionstringa) to do the reconversion. | If *wParam* is IGP\_SELECT, it returns one or more of the following values. | Requirement | Value | |-----------------------|------------------------------------------------------| | SELECT\_CAP\_CONVMODE | Inherits conversion mode when a new IME is selected. | | SELECT\_CAP\_SENTENCE | Inherits sentence mode when a new IME is selected. | If *wParam* is IGP\_GETIMEVERSION, it returns one or more of the following values. | Requirement | Value | |--------------|---------------------------------------------| | IMEVER\_0310 | The IME was created for Windows 3.1. | | IMEVER\_0400 | The IME was created for Windows 95 or later | This message is similar to [**ImmGetProperty**](/windows/desktop/api/imm/nf-imm-immgetproperty), except that it uses the current input locale. The application should call [**EM\_ISIME**](em-isime.md) before calling this function. Read more on docs.microsoft.com. Inserts one or more identical table rows with empty cells. Returns S\_OK if the table is inserted, or an error code if not. If the **cpStartRow** member of the [**TABLEROWPARMS**](/windows/desktop/api/Richedit/ns-richedit-tablerowparms) is –1, this message deletes the selected text (if any), and then inserts empty table rows with the row and cell parameters given by *wParam* and *lParam*. It leaves the selection pointing to the start of the first cell in the first row. The client can then populate the table cells by pointing the selection (or an [**ITextRange**](/windows/desktop/api/Tom/nn-tom-itextrange)) to the various cell end marks and inserting and formatting the desired text. Such text can include nested table rows. Alternatively, if the **cpStartRow** member of the **TABLEROWPARMS** is 0 or greater, table rows are inserted at the character position given by **cpStartRow**. This only changes the current selection if the table is inserted inside the selected text. A Microsoft Rich Edit table consists of a sequence of table rows which, in turn, consist of sequences of paragraphs. A table row starts with the special two-character delimiter paragraph U+FFF9 U+000D and ends with the two-character delimiter paragraph U+FFFB U+000D. Each cell is terminated by the cell mark U+0007, which is treated as a hard end-of-paragraph mark just as U+000D (CR) is. The table row and cell parameters are treated as special paragraph formatting of the table-row delimiters. The formatting contains the information in the [**TABLEROWPARMS**](/windows/desktop/api/Richedit/ns-richedit-tablerowparms) structure. The cell parameters given by the [**TABLECELLPARMS**](/windows/desktop/api/Richedit/ns-richedit-tablecellparms) structure are stored in an expanded version of the tabs array. This format allows tables to be nested within other tables, up to fifteen levels deep. Read more on docs.microsoft.com. Gets a pointer to the application-defined AutoCorrectProc function. Returns a pointer to the application-defined [*AutoCorrectProc*](/windows/desktop/api/Richedit/nc-richedit-autocorrectproc) function. Learn more about this API from docs.microsoft.com. Defines the current autocorrect callback procedure. If the operation succeeds, the return value is zero. If the operation fails, the return value is a nonzero value. Learn more about this API from docs.microsoft.com. Calls the autocorrect callback function that is stored by the EM\_SETAUTOCORRECTPROC message, provided that the text preceding the insertion point is a candidate for autocorrection. The return value is zero if the message succeeds, or nonzero if an error occurs. Learn more about this API from docs.microsoft.com. Retrieves the table parameters for a table row and the cell parameters for the specified number of cells. Returns S\_OK if successful, or one of the following error codes. | Return code | Description | |------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |
**E\_FAIL**
| Changes cannot be made. This can occur if the control is a plain-text or single-line control, or if the insertion point is inside a math object. It also occurs if tables are disabled if the [**EM\_SETEDITSTYLEEX**](em-seteditstyleex.md) message sets the **SES\_EX\_NOTABLE** value.
| |
**E\_INVALIDARG**
| The *wParam* or *lParam* is NULL or points to an invalid structure. The **cbRow** member of the [**TABLEROWPARMS**](/windows/desktop/api/Richedit/ns-richedit-tablerowparms) structure must equal `sizeof(TABLEROWPARMS)` or sizeof(TABLEROWPARMS) 2\*sizeof(long). The latter value is the size of the RichEdit 4.1 **TABLEROWPARMS** structure. The **cbCell** member of the **TABLEROWPARMS** structure must equal `sizeof(TABLECELLPARMS)`. The query character position must be at a table row delimiter. | |
**E\_OUTOFMEMORY**
| Insufficient memory is available.
| This message gets the table parameters for the row at the character position specified by the **cpStartRow** member of the [**TABLEROWPARMS**](/windows/desktop/api/Richedit/ns-richedit-tablerowparms) structure, and the number of cells specified by the **cCells** member of the [**TABLECELLPARMS**](/windows/desktop/api/Richedit/ns-richedit-tablecellparms) structure. The character position specified by the **cpStartRow** member of the [**TABLEROWPARMS**](/windows/desktop/api/Richedit/ns-richedit-tablerowparms) structure should be at the start of the table row, or at the end delimiter of the table row. If **cpStartRow** is set to 1, the character position is given by the current selection. In this case, position the selection at the end of the row (between the cell mark and the end delimiter of the table row), or select the row. Read more on docs.microsoft.com. Sets the current extended edit style flags. The return value is the state of the extended edit style flags after rich edit has attempted to implement your edit style changes. The edit style flags are a set of flags that indicate the current edit style. Learn more about this API from docs.microsoft.com. Retrieves the current extended edit style flags. Returns the extended edit style flags, which can include one or more of the following values. | Return code | Description | |------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |
**SES\_EX\_HANDLEFRIENDLYURL**
| Display friendly name links with the same text color and underlining as automatic links, provided that temporary formatting isn t used or uses text autocolor (default: 0).
| |
**SES\_EX\_MULTITOUCH**
| Enable touch support in Rich Edit. This includes selection, caret placement, and context-menu invocation. When this flag is not set, touch is emulated by mouse commands, which do not take touch-mode specifics into account (default: 0).
| |
**SES\_EX\_NOACETATESELECTION**
| Display selected text using classic Windows selection text and background colors instead of background acetate color (default: 0).
| |
**SES\_EX\_NOMATH**
| Disable insertion of math zones (default: 1). To enable math editing and display, send the [**EM\_SETEDITSTYLEEX**](em-seteditstyleex.md) message with *wParam* set to 0, and *lParam* set to **SES\_EX\_NOMATH**.
| |
**SES\_EX\_NOTABLE**
| Disable insertion of tables. The [**EM\_INSERTTABLE**](em-inserttable.md) message returns **E\_FAIL** and RTF tables are skipped (default: 0).
| |
**SES\_EX\_USESINGLELINE**
| Enable a multiline control to act like a single-line control with the ability to scroll vertically when the single-line height is greater than the window height (default: 0).
| |
**SES\_HIDETEMPFORMAT**
| Hide temporary formatting that is created when [**ITextFont.Reset**](/windows/desktop/api/Tom/nf-tom-itextfont-reset) is called with **tomApplyTmp**. For example, such formatting is used by spell checkers to display a squiggly underline under possibly misspelled words.
| |
**SES\_EX\_USEMOUSEWPARAM**
| Use *wParam* when handling the [**WM\_MOUSEMOVE**](/windows/desktop/inputdev/wm-mousemove) message and do not call [**GetAsyncKeyState**](/windows/desktop/api/winuser/nf-winuser-getasynckeystate).
| Learn more about this API from docs.microsoft.com. Gets the story type. Returns the story type, which can be a client-defined custom value, or one of the following values:
**[**tomCommentsStory**](/windows/win32/api/tom/ne-tom-tomconstants)**
**[**tomEndnotesStory**](/windows/win32/api/tom/ne-tom-tomconstants)**
**[**tomEvenPagesFooterStory**](/windows/win32/api/tom/ne-tom-tomconstants)**
**[**tomEvenPagesHeaderStory**](/windows/win32/api/tom/ne-tom-tomconstants)**
**[**tomFindStory**](/windows/win32/api/tom/ne-tom-tomconstants)**
**[**tomFirstPageFooterStory**](/windows/win32/api/tom/ne-tom-tomconstants)**
**[**tomFirstPageHeaderStory**](/windows/win32/api/tom/ne-tom-tomconstants)**
**[**tomFootnotesStory**](/windows/win32/api/tom/ne-tom-tomconstants)**
**[**tomMainTextStory**](/windows/win32/api/tom/ne-tom-tomconstants)**
**[**tomPrimaryFooterStory**](/windows/win32/api/tom/ne-tom-tomconstants)**
**[**tomPrimaryHeaderStory**](/windows/win32/api/tom/ne-tom-tomconstants)**
**[**tomReplaceStory**](/windows/win32/api/tom/ne-tom-tomconstants)**
**[**tomScratchStory**](/windows/win32/api/tom/ne-tom-tomconstants)**
**[**tomTextFrameStory**](/windows/win32/api/tom/ne-tom-tomconstants)**
**[**tomUnknownStory**](/windows/win32/api/tom/ne-tom-tomconstants)**
Learn more about this API from docs.microsoft.com. Sets the story type. The story type that was set. Learn more about this API from docs.microsoft.com. Retrieves the current ellipsis mode. If wparam is 0 and lparam is not NULL, the return value equals TRUE; otherwise, the return value equals FALSE. Learn more about this API from docs.microsoft.com. This message sets the current ellipsis mode. If wparam is 0 and lparam is one of the values in the table above, the return value equals TRUE; otherwise, the return value equals FALSE. Learn more about this API from docs.microsoft.com. Changes the parameters of rows in a table. Returns S\_OK if successful, or one of the following error codes. | Return code | Description | |------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |
**E\_FAIL**
| Changes cannot be made. This can occur if the control is a plain-text or single-line control, or if the insertion point is inside a math object. It also occurs if tables are disabled, or if the [**EM\_SETEDITSTYLEEX**](em-seteditstyleex.md) message sets the **SES\_EX\_NOTABLE** value.
| |
**E\_INVALIDARG**
| The *wParam* or *lParam* is NULL or points to an invalid structure. The **cCell** member of the [**TABLEROWPARMS**](/windows/desktop/api/Richedit/ns-richedit-tablerowparms) structure must be at least 1 and not more than 63. The **cbRow** member must equal `sizeof(TABLEROWPARMS)` or `sizeof(TABLEROWPARMS) 2*sizeof(long)`. The latter value is the size of the RichEdit 4.1 **TABLEROWPARMS** structure. The **cbCell** member of **TABLEROWPARMS** must equal `sizeof(TABLECELLPARMS)`. The insertion point must be at the start of a table or inside a table row, and the number of cells can only change by one. | |
**E\_OUTOFMEMORY**
| Insufficient memory is available.
| This message changes the parameters of the number of rows specified by the **cRow** member of the [**TABLEROWPARMS**](/windows/desktop/api/Richedit/ns-richedit-tablerowparms) structure, if the table has that many consecutive rows. If **cRow** is less than 0, the message iterates until the end of the table. If the new cell count differs from the current cell count by +1 or 1, it inserts or deletes the cell at the index specified by the **iCell** member of **TABLEROWPARMS**. The starting table row is identified by a character position. This position is specified by **cpStartRow** members with values that are greater than or equal to zero. The position should be inside the table row, but not inside a nested table, unless you want to change that table s parameters. If the **cpStartRow** member is 1, the character position is given by the current selection. For this, position the selection anywhere inside the table row, or select the row with the active end of the selection at the end of the table row. Retrieves the touch options that are associated with a rich edit control. Returns the value of the option specified by the *wParam* parameter. It is nonzero if *wParam* is **RTO\_SHOWHANDLES** and the touch grippers are visible; zero, otherwise. Learn more about this API from docs.microsoft.com. Sets the touch options associated with a rich edit control. This message returns zero. Learn more about this API from docs.microsoft.com. Replaces the selection with a blob that displays an image. Returns S\_OK if successful, or one of the following error codes. | Return code | Description | |------------------------------------------------------------------------------------------------|---------------------------------------------------------------| |
**E\_FAIL**
| Cannot insert the image.
| |
**E\_INVALIDARG**
| The *lParam* parameter is NULL or points to an invalid image. | |
**E\_OUTOFMEMORY**
| Insufficient memory is available.
| If the selection is an insertion point, the image blob is inserted at the insertion point. Sets the name of a rich edit control for UI Automation (UIA). TRUE if the name for UIA is successfully set, otherwise FALSE. Learn more about this API from docs.microsoft.com. Retrieves the current ellipsis state. The return value is TRUE if an ellipsis is being displayed and FALSE otherwise. Learn more about this API from docs.microsoft.com. Documentation varies per use. Refer to each: GetIconInfo, GetIconInfoEx, GetIconInfoEx, GetIconInfoExA, GetIconInfoExA, GetIconInfoExW, GetIconInfoExW, LoadIcon, LoadIcon, LoadIconA, LoadIconA, LoadIconW, LoadIconW. Documentation varies per use. Refer to each: GetIconInfo, GetIconInfoEx, GetIconInfoEx, GetIconInfoExA, GetIconInfoExA, GetIconInfoExW, GetIconInfoExW, LoadIcon, LoadIcon, LoadIconA, LoadIconA, LoadIconW, LoadIconW. Documentation varies per use. Refer to each: GetIconInfo, GetIconInfoEx, GetIconInfoEx, GetIconInfoExA, GetIconInfoExA, GetIconInfoExW, GetIconInfoExW, LoadIcon, LoadIcon, LoadIconA, LoadIconA, LoadIconW, LoadIconW. Documentation varies per use. Refer to each: GetIconInfo, GetIconInfoEx, GetIconInfoEx, GetIconInfoExA, GetIconInfoExA, GetIconInfoExW, GetIconInfoExW, LoadIcon, LoadIcon, LoadIconA, LoadIconA, LoadIconW, LoadIconW. Documentation varies per use. Refer to each: GetIconInfo, GetIconInfoEx, GetIconInfoEx, GetIconInfoExA, GetIconInfoExA, GetIconInfoExW, GetIconInfoExW, LoadIcon, LoadIcon, LoadIconA, LoadIconA, LoadIconW, LoadIconW. Documentation varies per use. Refer to each: GetIconInfo, GetIconInfoEx, GetIconInfoEx, GetIconInfoExA, GetIconInfoExA, GetIconInfoExW, GetIconInfoExW, LoadIcon, LoadIcon, LoadIconA, LoadIconA, LoadIconW, LoadIconW. Security Shield icon. Learn more about this API from docs.microsoft.com. Exclamation point icon. Learn more about this API from docs.microsoft.com. Hand-shaped icon. Learn more about this API from docs.microsoft.com. Asterisk icon. Learn more about this API from docs.microsoft.com. A Dynamic Data Exchange (DDE) client application sends a WM\_DDE\_INITIATE message to initiate a conversation with a server application responding to the specified application and topic names. If the low-order word of *lParam* is **NULL**, any server application can respond. If the high-order word of *lParam* is **NULL**, any topic is valid. Upon receiving a **WM\_DDE\_INITIATE** request with the high-order word of the *lParam* parameter set to **NULL**, a server must send a [**WM\_DDE\_ACK**](wm-dde-ack.md) message for each of the topics it supports. A Dynamic Data Exchange (DDE) application (client or server) posts a WM\_DDE\_TERMINATE message to terminate a conversation. To post this message, call the PostMessage function with the following parameters. A Dynamic Data Exchange (DDE) client application posts the WM\_DDE\_ADVISE message to a DDE server application to request the server to supply an update for a data item whenever the item changes. If a client application supports more than one clipboard format for a single topic and item, it can post multiple **WM\_DDE\_ADVISE** messages for the topic and item, specifying a different clipboard format with each message. Note that a server can support multiple formats only for hot data links, not warm data links. A Dynamic Data Exchange (DDE) client application posts a WM\_DDE\_UNADVISE message to inform a DDE server application that the specified item or a particular clipboard format for the item should no longer be updated. The client application allocates the high-order word of *lParam* by calling the [**GlobalAddAtom**](/windows/desktop/api/Winbase/nf-winbase-globaladdatoma) function. The server application posts the [**WM\_DDE\_ACK**](wm-dde-ack.md) message to respond positively or negatively. When posting **WM\_DDE\_ACK**, the server can either reuse the atom, or it can delete the atom and create a new one. Read more on docs.microsoft.com. The WM\_DDE\_ACK message notifies a Dynamic Data Exchange (DDE) application of the receipt and processing of the following messages WM\_DDE\_POKE, WM\_DDE\_EXECUTE, WM\_DDE\_DATA, WM\_DDE\_ADVISE, WM\_DDE\_UNADVISE, WM\_DDE\_INITIATE, or WM\_DDE\_REQUEST (in some cases). To post this message, call the PostMessage function with the following parameters. A Dynamic Data Exchange (DDE) server application posts a WM\_DDE\_DATA message to a DDE client application to pass a data item to the client or to notify the client of the availability of a data item. A Dynamic Data Exchange (DDE) client application posts a WM\_DDE\_REQUEST message to a DDE server application to request the value of a data item. To post this message, call the PostMessage function with the following parameters. A Dynamic Data Exchange (DDE) client application posts a WM\_DDE\_POKE message to a DDE server application. A Dynamic Data Exchange (DDE) client application posts a WM\_DDE\_EXECUTE message to a DDE server application to send a string to the server to be processed as a series of commands. The command string is a null-terminated string consisting of one or more opcode strings enclosed in single brackets (\[ \]). Each opcode string has the following syntax, where the *parameters* list is optional: *opcode parameters* The *opcode* is any application-defined single token. It cannot include spaces, commas, parentheses, brackets, or quotation marks. The *parameters* list can contain any application-defined value or values. Multiple parameters are separated by commas, and the entire parameter list is enclosed in parentheses. Parameters cannot include commas or parentheses except inside a quoted string. If a bracket or parenthesis character is to appear in a quoted string, it need not be doubled, as was the case under the old rules. The following are valid command strings: This doc was truncated. Read more on docs.microsoft.com. The WM\_CTLCOLOR message is used in 16-bit versions of Windows to change the color scheme of list boxes, the list boxes of combo boxes, message boxes, button controls, edit controls, static controls, and dialog boxes.Note  For information related to this message and 32-bit versions of Windows, see Remarks. If an application processes this message, it returns a handle to a brush. The system uses the brush to paint the background of the control. The **WM\_CTLCOLOR** message from 16-bit Windows has been replaced by more specific notifications. These replacements include the following: - [**WM\_CTLCOLORBTN**](../controls/wm-ctlcolorbtn.md) - [**WM\_CTLCOLOREDIT**](../controls/wm-ctlcoloredit.md) - [**WM\_CTLCOLORDLG**](../dlgbox/wm-ctlcolordlg.md) - [**WM\_CTLCOLORLISTBOX**](../controls/wm-ctlcolorlistbox.md) - [**WM\_CTLCOLORSCROLLBAR**](../controls/wm-ctlcolorscrollbar.md) - [**WM\_CTLCOLORSTATIC**](../controls/wm-ctlcolorstatic.md) Read more on docs.microsoft.com. Posted to a window when the cursor hovers over the client area of the window for the period of time specified in a prior call to TrackMouseEvent. If an application processes this message, it should return zero. Hover tracking stops when **WM\_MOUSEHOVER** is generated. The application must call [**TrackMouseEvent**](/windows/win32/api/winuser/nf-winuser-trackmouseevent) again if it requires further tracking of mouse hover behavior. Use the following code to obtain the horizontal and vertical position: This doc was truncated. Read more on docs.microsoft.com. Posted to a window when the cursor leaves the client area of the window specified in a prior call to TrackMouseEvent. If an application processes this message, it should return zero. All tracking requested by [**TrackMouseEvent**](/windows/win32/api/winuser/nf-winuser-trackmouseevent) is canceled when this message is generated. The application must call **TrackMouseEvent** when the mouse reenters its window if it requires further tracking of mouse hover behavior. An application sends the WM\_CHOOSEFONT\_GETLOGFONT message to a Font dialog box to retrieve information about the user's current font selections. This message does not return a value. The [**ChooseFont**](/windows/win32/api/commdlg/ns-commdlg-choosefonta) function creates a **Font** dialog box. When the user closes the **Font** dialog box, the **ChooseFont** function returns information about the user's font selections in the [**CHOOSEFONT**](/windows/win32/api/commdlg/ns-commdlg-choosefonta) structure. The **lpLogFont** member of the **CHOOSEFONT** structure is a pointer to a [**LOGFONT**](/windows/win32/api/wingdi/ns-wingdi-logfonta) structure. Use the **WM\_CHOOSEFONT\_GETLOGFONT** message to get information about the user's current font selections while the **Font** dialog box is open. For example, if you enable the **Apply** button in the **Font** dialog box, send the message to get the font information to apply to the current text selection. Typically, you enable a [*CFHookProc*](/windows/win32/api/commdlg/nc-commdlg-lpcfhookproc) hook procedure to process [**WM\_COMMAND**](/windows/desktop/menurc/wm-command) messages for the **Apply** button. When the user clicks the **Apply** button, the hook procedure sends the **WM\_CHOOSEFONT\_GETLOGFONT** message to the dialog box. Read more on docs.microsoft.com. An application sends the WM\_CHOOSEFONT\_SETLOGFONT message to a Font dialog box to set the current logical font information. This message has no return value. When you call the [**ChooseFont**](/windows/win32/api/commdlg/ns-commdlg-choosefonta) function to create a **Font** dialog box, you can use the **lpLogFont** member of the [**CHOOSEFONT**](/windows/win32/api/commdlg/ns-commdlg-choosefonta) structure to specify a [**LOGFONT**](/windows/win32/api/wingdi/ns-wingdi-logfonta) structure containing initial values for the dialog box. Use the **WM\_CHOOSEFONT\_SETLOGFONT** message to specify a **LOGFONT** structure with different values while the **Font** dialog box is open. Typically, you would send the **WM\_CHOOSEFONT\_SETLOGFONT** message from a [**CFHookProc**](/windows/win32/api/commdlg/nc-commdlg-lpcfhookproc) hook procedure. The hook procedure can also send the [**WM\_CHOOSEFONT\_GETLOGFONT**](wm-choosefont-getlogfont.md) and [**WM\_CHOOSEFONT\_SETFLAGS**](wm-choosefont-setflags.md) messages. Read more on docs.microsoft.com. An application sends the WM\_CHOOSEFONT\_SETFLAGS message to a Font dialog box to set the display options for the dialog box. No return value. The [**ChooseFont**](/windows/win32/api/commdlg/ns-commdlg-choosefonta) function creates a **Font** dialog box and uses a [**CHOOSEFONT**](/windows/win32/api/commdlg/ns-commdlg-choosefonta) structure to specify the initial values for the **Flags** member. Use the **WM\_CHOOSEFONT\_SETFLAGS** message to specify different values for the **Flags** member while the **Font** dialog box is open. Typically, you should send the **WM\_CHOOSEFONT\_SETFLAGS** message from a [**CFHookProc**](/windows/win32/api/commdlg/nc-commdlg-lpcfhookproc) hook procedure. Read more on docs.microsoft.com. Notifies a PagePaintHook hook procedure of the coordinates of the sample page rectangle in the Page Setup dialog box. The dialog box sends this message when it is about to draw the contents of the sample page. If the hook procedure returns **TRUE**, the dialog box sends no more messages and does not draw in the sample page until the next time the system needs to redraw the sample page. If the hook procedure returns **FALSE**, the dialog box sends the remaining messages of the drawing sequence. The **Page Setup** dialog box includes an image of a sample page that shows how the user's selections affect the appearance of the printed output. When you call the [**PageSetupDlg**](/previous-versions/windows/desktop/legacy/ms646937(v=vs.85)) function, you can provide a [*PagePaintHook*](/windows/win32/api/commdlg/nc-commdlg-lppagepainthook) hook procedure to customize the appearance of the sample page. Whenever the dialog box is about to draw the contents of the sample page, the dialog box sends a sequence of messages to the hook procedure. Notifies a PagePaintHook hook procedure of the coordinates of the margin rectangle in the sample page. A Page Setup dialog box sends this message when it is about to draw the contents of the sample page. If the hook procedure returns **TRUE**, the dialog box sends no more messages and does not draw in the sample page until the next time the system needs to redraw the sample page. If the hook procedure returns **FALSE**, the dialog box sends the remaining messages of the drawing sequence. The **Page Setup** dialog box includes an image of a sample page that shows how the user's selections affect the appearance of the printed output. When you call the [**PageSetupDlg**](/previous-versions/windows/desktop/legacy/ms646937(v=vs.85)) function, you can provide a [*PagePaintHook*](/windows/win32/api/commdlg/nc-commdlg-lppagepainthook) hook procedure to customize the appearance of the sample page. Whenever the dialog box is about to draw the contents of the sample page, the dialog box sends a sequence of messages to the hook procedure. Notifies the hook procedure of a Page Setup dialog box, PagePaintHook, that the dialog box is about to draw the margin rectangle of the sample page. If the hook procedure returns **TRUE**, the dialog box does not draw the margin rectangle in the sample page. If the hook procedure returns **FALSE**, the dialog box draws the margin rectangle in the sample page. The **Page Setup** dialog box includes an image of a sample page that shows how the user's selections affect the appearance of the printed output. When you call the [**PageSetupDlg**](/previous-versions/windows/desktop/legacy/ms646937(v=vs.85)) function, you can provide a [*PagePaintHook*](/windows/win32/api/commdlg/nc-commdlg-lppagepainthook) hook procedure to customize the appearance of the sample page. Whenever the dialog box is about to draw the contents of the sample page, the dialog box sends a sequence of messages to the hook procedure. Notifies the hook procedure of a Page Setup dialog box, PagePaintHook, that the dialog box is about to draw Greek text inside the margin rectangle of the sample page. If the hook procedure returns **TRUE**, the dialog box does not draw the Greek text portion of the sample page. If the hook procedure returns **FALSE**, the dialog box draws the Greek text portion of the sample page. The **Page Setup** dialog box includes an image of a sample page that shows how the user's selections affect the appearance of the printed output. When you call the [**PageSetupDlg**](/previous-versions/windows/desktop/legacy/ms646937(v=vs.85)) function, you can provide a [*PagePaintHook*](/windows/win32/api/commdlg/nc-commdlg-lppagepainthook) hook procedure to customize the appearance of the sample page. Whenever the dialog box is about to draw the contents of the sample page, the dialog box sends a sequence of messages to the hook procedure. Notifies the hook procedure of a Page Setup dialog box, PagePaintHook, that the dialog box is about to draw the envelope-stamp rectangle of the sample page. If the hook procedure returns **TRUE**, the dialog box does not draw the envelope-stamp portion of the sample page. If the hook procedure returns **FALSE**, the dialog box draws the envelope-stamp portion of the sample page. The **Page Setup** dialog box includes an image of a sample page that shows how the user's selections affect the appearance of the printed output. When you call the [**PageSetupDlg**](/previous-versions/windows/desktop/legacy/ms646937(v=vs.85)) function, you can provide a [*PagePaintHook*](/windows/win32/api/commdlg/nc-commdlg-lppagepainthook) hook procedure to customize the appearance of the sample page. Whenever the dialog box is about to draw the contents of the sample page, the dialog box sends a sequence of messages to the hook procedure. A hook procedure receives this message only if the selected paper type is an envelope. Read more on docs.microsoft.com. Notifies the hook procedure of a Page Setup dialog box, PagePaintHook, that the dialog box is about to draw the return address portion of an envelope sample page. If the hook procedure returns **TRUE**, the dialog box does not draw the return address portion of an envelope sample page. If the hook procedure returns **FALSE**, the dialog box draws the return address portion of an envelope sample page. If the paper type is not an envelope, the return value has no effect. The **Page Setup** dialog box includes an image of a sample page that shows how the user's selections affect the appearance of the printed output. When you call the [**PageSetupDlg**](/previous-versions/windows/desktop/legacy/ms646937(v=vs.85)) function, you can provide a [*PagePaintHook*](/windows/win32/api/commdlg/nc-commdlg-lppagepainthook) hook procedure to customize the appearance of the sample page. Whenever the dialog box is about to draw the contents of the sample page, the dialog box sends a sequence of messages to the hook procedure. WM_CPL_LAUNCH message - This message is not supported. Learn more about this API from docs.microsoft.com. WM_CPL_LAUNCHED message - This message is not supported. Learn more about this API from docs.microsoft.com. The WM\_TABLET\_ADDED message is posted when a tablet device is added to Windows. This message is sent to all top-level windows in the system, including disabled or invisible unowned windows, overlapped windows, and pop-up windows; but the message is not sent to child windows. The indexes passed in *wParam* are related to the index used by the [**ITabletManager::GetTablet**](/previous-versions/windows/desktop/legacy/aa373683(v=vs.85)) method. Read more on docs.microsoft.com. The WM\_TABLET\_DELETED message is posted when a tablet device is removed from Windows. This message is sent to all top-level windows in the system, including disabled or invisible unowned windows, overlapped windows, and pop-up windows; but the message is not sent to child windows. The indexes passed in *wParam* are related to the index used by the [**ITabletManager::GetTablet**](/previous-versions/windows/desktop/legacy/aa373683(v=vs.85)) method. Read more on docs.microsoft.com. Sent when a user performs a pen flick. A window receives this message through its WindowProc function. A pen flick is a unidirectional pen gesture that requires the user to contact the digitizer in a quick, straight flicking motion. A flick is characterized by high speed and a high degree of straightness. A flick is identified by its direction. Flicks can be made in eight directions corresponding to the cardinal and secondary compass directions. When a pen flick occurs, Windows first notifies an application by sending a **WM\_TABLET\_FLICK** message, which a window receives through its [*WindowProc*](/previous-versions/windows/desktop/legacy/ms633573(v=vs.85)) function. Return the **FLICK\_WM\_HANDLED\_MASK** constant, described in [Flicks Constants](flicks-constants.md), to indicate that the application responded to the **WM\_TABLET\_FLICK** message. If the application does not return **FLICK\_WM\_HANDLED\_MASK**, Windows performs the default action specified in the flicks control panel by sending a follow-up notification, such as [**WM\_APPCOMMAND**](../inputdev/wm-appcommand.md), [**WM\_VSCROLL**](../controls/wm-vscroll.md), or [**WM\_KEYDOWN**](../inputdev/wm-keydown.md), depending on which action is associated with the pen flick. Use caution when handling the **WM\_TABLET\_FLICK** message. **WM\_TABLET\_FLICK** is passed via the [**SendMessageTimeout**](/windows/win32/api/winuser/nf-winuser-sendmessagetimeouta) function. If you call methods on a COM interface, that object must be within the same process. If not, COM throws an exception. Read more on docs.microsoft.com. Sent when the system asks a window which system gestures it would like to receive. By handling this message, you can dynamically disable flicks for regions of a window. > [!Note] > The *lParam* can be converted to x-coordinates and y-coordinates by using the `GET_X_LPARAM` and `GET_Y_LPARAM` macros. By default, your window will receive all system gesture events. You can choose which events you would like your window to receive and which events you would like disabled by responding to the **WM\_TABLET\_QUERYSYSTEMGESTURESTATUS** message in your **WndProc**. The **WM\_TABLET\_QUERYSYSTEMGESTURESTATUS** message is defined in tpcshrd.h. The values to enable and disable system tablet system gestures are also defined in tpcshrd.h as follows: This doc was truncated. Read more on docs.microsoft.com. Notifies a window that the user clicked the right mouse button (right-clicked) in the window. No return value. A window can process this message by displaying a shortcut menu using the [**TrackPopupMenu**](/windows/desktop/api/Winuser/nf-winuser-trackpopupmenu) or [**TrackPopupMenuEx**](/windows/desktop/api/Winuser/nf-winuser-trackpopupmenuex) functions. To obtain the horizontal and vertical positions, use the following code. This doc was truncated. Read more on docs.microsoft.com. The WM\_UNICHAR message can be used by an application to post input to other windows. An application should return zero if it processes this message. The **WM\_UNICHAR** message is similar to [**WM\_CHAR**](wm-char.md), but it uses Unicode Transformation Format (UTF)-32, whereas **WM\_CHAR** uses UTF-16. This message is designed to send or post Unicode characters to ANSI windows and can handle Unicode Supplementary Plane characters. Because there is not necessarily a one-to-one correspondence between keys pressed and character messages generated, the information in the high-order word of the *lParam* parameter is generally not useful to applications. The information in the high-order word applies only to the most recent [**WM\_KEYDOWN**](wm-keydown.md) message that precedes the posting of the **WM\_UNICHAR** message. For enhanced 101- and 102-key keyboards, extended keys are the right ALT and the right CTRL keys on the main section of the keyboard; the INS, DEL, HOME, END, PAGE UP, PAGE DOWN and arrow keys in the clusters to the left of the numeric keypad; and the divide (/) and ENTER keys in the numeric keypad. Some other keyboards may support the extended-key bit in the *lParam* parameter. Read more on docs.microsoft.com. The WM\_PRINTCLIENT message is sent to a window to request that it draw its client area in the specified device context, most commonly in a printer device context. A window can process this message in much the same manner as [**WM\_PAINT**](./wm-paint.md), except that [**BeginPaint**](/windows/desktop/api/Winuser/nf-winuser-beginpaint) and [**EndPaint**](/windows/desktop/api/Winuser/nf-winuser-endpaint) need not be called (a device context is provided), and the window should draw its entire client area rather than just the invalid region. Windows that can be used anywhere in the system, such as controls, should process this message. It is probably worthwhile for other windows to process this message as well because it is relatively easy to implement. The [AnimateWindow](/windows/desktop/api/winuser/nf-winuser-animatewindow) function requires that the window being animated implements the **WM\_PRINTCLIENT** message. Read more on docs.microsoft.com. Sent by a common control to its parent window when an event has occurred or the control requires some information. The return value is ignored except for notification messages that specify otherwise. The destination of the message must be the **HWND** of the parent of the control. This value can be obtained by using [**GetParent**](/windows/desktop/api/winuser/nf-winuser-getparent), as shown in the following example, where *m\_controlHwnd* is the **HWND** of the control itself. This doc was truncated. Read more on docs.microsoft.com. Notifies an application of a change to the hardware configuration of a device or the computer. Return **TRUE** to grant the request. Return **BROADCAST\_QUERY\_DENY** to deny the request. For devices that offer software-controllable features, such as ejection and locking, the system typically sends a [DBT\_DEVICEREMOVEPENDING](dbt-deviceremovepending.md) message to let applications and device drivers end their use of the device gracefully. If the system forcibly removes a device, it may not send a [DBT\_DEVICEQUERYREMOVE](dbt-devicequeryremove.md) message before doing so. Performs no operation. An application sends the WM\_NULL message if it wants to post a message that the recipient window will ignore. Type: **LRESULT** An application returns zero if it processes this message. For example, if an application has installed a **WH\_GETMESSAGE** hook and wants to prevent a message from being processed, the [**GetMsgProc**](/previous-versions/windows/desktop/legacy/ms644981(v=vs.85)) callback function can change the message number to **WM\_NULL** so the recipient will ignore it. As another example, an application can check if a window is responding to messages by sending the **WM\_NULL** message with the [**SendMessageTimeout**](/windows/win32/api/winuser/nf-winuser-sendmessagetimeouta) function. Read more on docs.microsoft.com. Sent when an application requests that a window be created by calling the CreateWindowEx or CreateWindow function. Type: **LRESULT** If an application processes this message, it should return zero to continue creation of the window. If the application returns –1, the window is destroyed and the [**CreateWindowEx**](/windows/win32/api/winuser/nf-winuser-createwindowexa) or [**CreateWindow**](/windows/win32/api/winuser/nf-winuser-createwindowa) function returns a **NULL** handle. Learn more about this API from docs.microsoft.com. Sent when a window is being destroyed. It is sent to the window procedure of the window being destroyed after the window is removed from the screen. Type: **LRESULT** If an application processes this message, it should return zero. If the window being destroyed is part of the clipboard viewer chain (set by calling the [**SetClipboardViewer**](/windows/win32/api/winuser/nf-winuser-setclipboardviewer) function), the window must remove itself from the chain by processing the [**ChangeClipboardChain**](/windows/win32/api/winuser/nf-winuser-changeclipboardchain) function before returning from the **WM\_DESTROY** message. Sent after a window has been moved. Type: **LRESULT** If an application processes this message, it should return zero. The parameters are given in screen coordinates for overlapped and pop-up windows and in parent-client coordinates for child windows. The following example demonstrates how to obtain the position from the *lParam* parameter. This doc was truncated. Read more on docs.microsoft.com. Sent to a window after its size has changed. Type: **LRESULT** If an application processes this message, it should return zero. If the [**SetScrollPos**](https://msdn.microsoft.com/library/Cc411085(v=MSDN.10).aspx) or [**MoveWindow**](/windows/win32/api/winuser/nf-winuser-movewindow) function is called for a child window as a result of the **WM\_SIZE** message, the *bRedraw* or *bRepaint* parameter should be nonzero to cause the window to be repainted. Although the width and height of a window are 32-bit values, the *lParam* parameter contains only the low-order 16 bits of each. The [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function sends the **WM\_SIZE** and **WM\_MOVE** messages when it processes the [**WM\_WINDOWPOSCHANGED**](wm-windowposchanged.md) message. The **WM\_SIZE** and **WM\_MOVE** messages are not sent if an application handles the **WM\_WINDOWPOSCHANGED** message without calling **DefWindowProc**. Read more on docs.microsoft.com. Sent to both the window being activated and the window being deactivated. If an application processes this message, it should return zero. If the window is being activated and is not minimized, the [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function sets the keyboard focus to the window. If the window is activated by a mouse click, it also receives a [**WM\_MOUSEACTIVATE**](wm-mouseactivate.md) message. Sent to a window after it has gained the keyboard focus. An application should return zero if it processes this message. To display a caret, an application should call the appropriate caret functions when it receives the **WM\_SETFOCUS** message. Sent to a window immediately before it loses the keyboard focus. An application should return zero if it processes this message. If an application is displaying a caret, the caret should be destroyed at this point. While processing this message, do not make any function calls that display or activate a window. This causes the thread to yield control and can cause the application to stop responding to messages. For more information, see [Message Deadlocks](/windows/desktop/winmsg/about-messages-and-message-queues). Read more on docs.microsoft.com. Sent when an application changes the enabled state of a window. Type: **LRESULT** If an application processes this message, it should return zero. Learn more about this API from docs.microsoft.com. You send the **WM_SETREDRAW** message to a window to allow changes in that window to be redrawn, or to prevent changes in that window from being redrawn. Your application should return 0 if it processes this message. This message can be useful if your application must add several items to a list box. Your application can call this message with *wParam* set to **FALSE**, add the items, and then call the message again with *wParam* set to **TRUE**. Finally, your application can call [**RedrawWindow**](/windows/win32/api/Winuser/nf-winuser-redrawwindow)(*hWnd*, **NULL**, **NULL**, RDW\_ERASE \| RDW\_FRAME \| RDW\_INVALIDATE \| RDW\_ALLCHILDREN) to cause the list box to be repainted. > [!NOTE] > You should use [**RedrawWindow**](/windows/win32/api/Winuser/nf-winuser-redrawwindow) with the specified flags, instead of [**InvalidateRect**](/windows/win32/api/Winuser/nf-winuser-invalidaterect), because the former is necessary for some controls that have nonclient area of their own, or have window styles that cause them to be given a nonclient area (such as **WS_THICKFRAME**, **WS_BORDER**, or **WS_EX_CLIENTEDGE**). If the control does not have a nonclient area, then **RedrawWindow** with these flags will do only as much invalidation as **InvalidateRect** would. Passing a **WM_SETREDRAW** message to the **DefWindowProc** function removes the **WS_VISIBLE** style from the window when *wParam* is set to **FALSE**. Although the window content remains visible on screen, the [**IsWindowVisible**](/windows/win32/api/winuser/nf-winuser-iswindowvisible) function returns **FALSE** when called on a window in this state. Passing a **WM_SETREDRAW** message to the **DefWindowProc** function adds the **WS_VISIBLE** style to the window, if not set, when *wParam* is set to **TRUE**. If your application sends the **WM_SETREDRAW** message with *wParam* set to **TRUE** to a hidden window, then the window becomes visible. **Windows 10 and later; Windows Server 2016 and later**. The system sets a property named *SysSetRedraw* on a window whose window procedure passes **WM_SETREDRAW** messages to **DefWindowProc**. You can use the [**GetProp**](/windows/win32/api/Winuser/nf-winuser-getpropa) function to get the property value when it's available. **GetProp** returns a non-zero value when redraw is disabled. **GetProp** will return zero when redraw is enabled, or when the window property doesn't exist. Read more on docs.microsoft.com. Sets the text of a window. Type: **LRESULT** The return value is **TRUE** if the text is set. It is **FALSE** (for an edit control), **LB\_ERRSPACE** (for a list box), or **CB\_ERRSPACE** (for a combo box) if insufficient space is available to set the text in the edit control. It is **CB\_ERR** if this message is sent to a combo box without an edit control. The [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function sets and displays the window text. For an edit control, the text is the contents of the edit control. For a combo box, the text is the contents of the edit-control portion of the combo box. For a button, the text is the button name. For other windows, the text is the window title. This message does not change the current selection in the list box of a combo box. An application should use the [**CB\_SELECTSTRING**](../controls/cb-selectstring.md) message to select the item in a list box that matches the text in the edit control. Read more on docs.microsoft.com. Copies the text that corresponds to a window into a buffer provided by the caller. Type: **LRESULT** The return value is the number of characters copied, not including the terminating null character. The [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function copies the text associated with the window into the specified buffer and returns the number of characters copied. Note, for non-text static controls this gives you the text with which the control was originally created, that is, the ID number. However, it gives you the ID of the non-text static control as originally created. That is, if you subsequently used a **STM\_SETIMAGE** to change it the original ID would still be returned. For an edit control, the text to be copied is the content of the edit control. For a combo box, the text is the content of the edit control (or static-text) portion of the combo box. For a button, the text is the button name. For other windows, the text is the window title. To copy the text of an item in a list box, an application can use the [**LB\_GETTEXT**](../controls/lb-gettext.md) message. When the **WM\_GETTEXT** message is sent to a static control with the **SS\_ICON** style, a handle to the icon will be returned in the first four bytes of the buffer pointed to by *lParam*. This is true only if the [**WM\_SETTEXT**](wm-settext.md) message has been used to set the icon. **Rich Edit:** If the text to be copied exceeds 64K, use either the [**EM\_STREAMOUT**](../controls/em-streamout.md) or [**EM\_GETSELTEXT**](../controls/em-getseltext.md) message. Sending a **WM\_GETTEXT** message to a non-text static control, such as a static bitmap or static icon control, does not return a string value. Instead, it returns zero. In addition, in early versions of Windows, applications could send a **WM\_GETTEXT** message to a non-text static control to retrieve the control's ID. To retrieve a control's ID, applications can use [**GetWindowLong**](/windows/win32/api/winuser/nf-winuser-getwindowlonga) passing **GWL\_ID** as the index value or [**GetWindowLongPtr**](/windows/win32/api/winuser/nf-winuser-getwindowlongptra) using **GWLP\_ID**. Read more on docs.microsoft.com. Determines the length, in characters, of the text associated with a window. Type: **LRESULT** The return value is the length of the text in characters, not including the terminating null character. For an edit control, the text to be copied is the content of the edit control. For a combo box, the text is the content of the edit control (or static-text) portion of the combo box. For a button, the text is the button name. For other windows, the text is the window title. To determine the length of an item in a list box, an application can use the [**LB\_GETTEXTLEN**](../controls/lb-gettextlen.md) message. When the **WM\_GETTEXTLENGTH** message is sent, the [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function returns the length, in characters, of the text. Under certain conditions, the **DefWindowProc** function returns a value that is larger than the actual length of the text. This occurs with certain mixtures of ANSI and Unicode, and is due to the system allowing for the possible existence of double-byte character set (DBCS) characters within the text. The return value, however, will always be at least as large as the actual length of the text; you can thus always use it to guide buffer allocation. This behavior can occur when an application uses both ANSI functions and common dialogs, which use Unicode. To obtain the exact length of the text, use the [**WM\_GETTEXT**](wm-gettext.md), [**LB\_GETTEXT**](../controls/lb-gettext.md), or [**CB\_GETLBTEXT**](../controls/cb-getlbtext.md) messages, or the [**GetWindowText**](/windows/win32/api/winuser/nf-winuser-getwindowtexta) function. Sending a **WM\_GETTEXTLENGTH** message to a non-text static control, such as a static bitmap or static icon controlc, does not return a string value. Instead, it returns zero. Read more on docs.microsoft.com. The WM\_PAINT message is sent when the system or another application makes a request to paint a portion of an application's window. An application returns zero if it processes this message. The **WM\_PAINT** message is generated by the system and should not be sent by an application. To force a window to draw into a specific device context, use the [**WM\_PRINT**](wm-print.md) or [**WM\_PRINTCLIENT**](wm-printclient.md) message. Note that this requires the target window to support the **WM\_PRINTCLIENT** message. Most common controls support the **WM\_PRINTCLIENT** message. The [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function validates the update region. The function may also send the [**WM\_NCPAINT**](wm-ncpaint.md) message to the window procedure if the window frame must be painted and send the [**WM\_ERASEBKGND**](../winmsg/wm-erasebkgnd.md) message if the window background must be erased. The system sends this message when there are no other messages in the application's message queue. [**DispatchMessage**](/windows/win32/api/winuser/nf-winuser-dispatchmessage) determines where to send the message; [**GetMessage**](/windows/win32/api/winuser/nf-winuser-getmessage) determines which message to dispatch. **GetMessage** returns the **WM\_PAINT** message when there are no other messages in the application's message queue, and **DispatchMessage** sends the message to the appropriate window procedure. A window may receive internal paint messages as a result of calling [**RedrawWindow**](/windows/desktop/api/Winuser/nf-winuser-redrawwindow) with the RDW\_INTERNALPAINT flag set. In this case, the window may not have an update region. An application may call the [**GetUpdateRect**](/windows/desktop/api/Winuser/nf-winuser-getupdaterect) function to determine whether the window has an update region. If **GetUpdateRect** returns zero, the application need not call the [**BeginPaint**](/windows/desktop/api/Winuser/nf-winuser-beginpaint) and [**EndPaint**](/windows/desktop/api/Winuser/nf-winuser-endpaint) functions. An application must check for any necessary internal painting by looking at its internal data structures for each **WM\_PAINT** message, because a **WM\_PAINT** message may have been caused by both a non-NULL update region and a call to [**RedrawWindow**](/windows/desktop/api/Winuser/nf-winuser-redrawwindow) with the RDW\_INTERNALPAINT flag set. The system sends an internal **WM\_PAINT** message only once. After an internal **WM\_PAINT** message is returned from [**GetMessage**](/windows/win32/api/winuser/nf-winuser-getmessage) or [**PeekMessage**](/windows/win32/api/winuser/nf-winuser-peekmessagea) or is sent to a window by [**UpdateWindow**](/windows/desktop/api/Winuser/nf-winuser-updatewindow), the system does not post or send further **WM\_PAINT** messages until the window is invalidated or until [**RedrawWindow**](/windows/desktop/api/Winuser/nf-winuser-redrawwindow) is called again with the RDW\_INTERNALPAINT flag set. For some common controls, the default **WM\_PAINT** message processing checks the *wParam* parameter. If *wParam* is non-NULL, the control assumes that the value is an HDC and paints using that device context. Read more on docs.microsoft.com. Sent as a signal that a window or an application should terminate. Type: **LRESULT** If an application processes this message, it should return zero. An application can prompt the user for confirmation, prior to destroying a window, by processing the **WM\_CLOSE** message and calling the [**DestroyWindow**](/windows/win32/api/winuser/nf-winuser-destroywindow) function only if the user confirms the choice. By default, the [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function calls the [**DestroyWindow**](/windows/win32/api/winuser/nf-winuser-destroywindow) function to destroy the window. Read more on docs.microsoft.com. The WM\_QUERYENDSESSION message is sent when the user chooses to end the session or when an application calls one of the system shutdown functions. Applications should respect the user's intentions and return **TRUE**. By default, the [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function returns **TRUE** for this message. If shutting down would corrupt the system or media that is being burned, the application can return **FALSE**. However, it is good practice to respect the user's actions. When an application returns **TRUE** for this message, it receives the [**WM\_ENDSESSION**](wm-endsession.md) message, regardless of how the other applications respond to the **WM\_QUERYENDSESSION** message. Each application should return **TRUE** or **FALSE** immediately upon receiving this message, and defer any cleanup operations until it receives the **WM\_ENDSESSION** message. Applications can display a user interface prompting the user for information at shutdown, however it is not recommended. After five seconds, the system displays information about the applications that are preventing shutdown and allows the user to terminate them. For example, Windows XP displays a dialog box, while Windows Vista displays a full screen with additional information about the applications blocking shutdown. If your application must block or postpone system shutdown, use the [**ShutdownBlockReasonCreate**](/windows/desktop/api/Winuser/nf-winuser-shutdownblockreasoncreate) function. For more information, see [Shutdown Changes for Windows Vista](shutdown-changes-for-windows-vista.md). Console applications can use the [**SetConsoleCtrlHandler**](/windows/console/setconsolectrlhandler) function to receive shutdown notification. Service applications can use the [**RegisterServiceCtrlHandlerEx**](/windows/win32/api/winsvc/nf-winsvc-registerservicectrlhandlerexa) function to receive shutdown notifications in a handler routine. Read more on docs.microsoft.com. Sent to an icon when the user requests that the window be restored to its previous size and position. Type: **LRESULT** If the icon can be opened, an application that processes this message should return **TRUE**; otherwise, it should return **FALSE** to prevent the icon from being opened. By default, the [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function returns **TRUE**. While processing this message, the application should not perform any action that would cause an activation or focus change (for example, creating a dialog box). Read more on docs.microsoft.com. The WM\_ENDSESSION message is sent to an application after the system processes the results of the WM\_QUERYENDSESSION message. The WM\_ENDSESSION message informs the application whether the session is ending. If an application processes this message, it should return zero. Applications that have unsaved data could save the data to a temporary location and restore it the next time the application starts. It is recommended that applications save their data and state frequently; for example, automatically save data between save operations initiated by the user to reduce the amount of data to be saved at shutdown. The application need not call the [**DestroyWindow**](/windows/win32/api/winuser/nf-winuser-destroywindow) or [**PostQuitMessage**](/windows/win32/api/winuser/nf-winuser-postquitmessage) function when the session is ending. Read more on docs.microsoft.com. Indicates a request to terminate an application, and is generated when the application calls the PostQuitMessage function. This message causes the GetMessage function to return zero. Type: **LRESULT** This message does not have a return value because it causes the message loop to terminate before the message is sent to the application's window procedure. The **WM\_QUIT** message is not associated with a window and therefore will never be received through a window's window procedure. It is retrieved only by the [**GetMessage**](/windows/win32/api/winuser/nf-winuser-getmessage) or [**PeekMessage**](/windows/win32/api/winuser/nf-winuser-peekmessagea) functions. Do not post the **WM\_QUIT** message using the [**PostMessage**](/windows/win32/api/winuser/nf-winuser-postmessagea) function; use [**PostQuitMessage**](/windows/win32/api/winuser/nf-winuser-postquitmessage). Read more on docs.microsoft.com. Sent when the window background must be erased (for example, when a window is resized). The message is sent to prepare an invalidated portion of a window for painting. Type: **LRESULT** An application should return nonzero if it erases the background; otherwise, it should return zero. The [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function erases the background by using the class background brush specified by the **hbrBackground** member of the [**WNDCLASS**](/windows/win32/api/winuser/ns-winuser-wndclassa) structure. If **hbrBackground** is **NULL**, the application should process the **WM\_ERASEBKGND** message and erase the background. An application should return nonzero in response to **WM\_ERASEBKGND** if it processes the message and erases the background; this indicates that no further erasing is required. If the application returns zero, the window will remain marked for erasing. (Typically, this indicates that the **fErase** member of the [**PAINTSTRUCT**](/windows/win32/api/winuser/ns-winuser-paintstruct) structure will be **TRUE**.) Read more on docs.microsoft.com. The WM\_SYSCOLORCHANGE message is sent to all top-level windows when a change is made to a system color setting. The system sends a [**WM\_PAINT**](wm-paint.md) message to any window that is affected by a system color change. Applications that have brushes using the existing system colors should delete those brushes and re-create them using the new system colors. Top level windows that use common controls must forward the **WM\_SYSCOLORCHANGE** message to the controls; otherwise, the controls will not be notified of the color change. This ensures that the colors used by your common controls are consistent with those used by other user interface objects. For example, a toolbar control uses the "3D Objects" color to draw its buttons. If the user changes the 3D Objects color but the **WM\_SYSCOLORCHANGE** message is not forwarded to the toolbar, the toolbar buttons will remain in their original color while the color of other buttons in the system changes. Read more on docs.microsoft.com. Sent to a window when the window is about to be hidden or shown. Type: **LRESULT** If an application processes this message, it should return zero. The [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function hides or shows the window, as specified by the message. If a window has the [**WS\_VISIBLE**](window-styles.md) style when it is created, the window receives this message after it is created, but before it is displayed. A window also receives this message when its visibility state is changed by the [**ShowWindow**](/windows/win32/api/winuser/nf-winuser-showwindow) or [**ShowOwnedPopups**](/windows/win32/api/winuser/nf-winuser-showownedpopups) function. The **WM\_SHOWWINDOW** message is not sent under the following circumstances: - When a top-level, overlapped window is created with the [**WS\_MAXIMIZE**](window-styles.md) or **WS\_MINIMIZE** style. - When the **SW\_SHOWNORMAL** flag is specified in the call to the [**ShowWindow**](/windows/win32/api/winuser/nf-winuser-showwindow) function. Read more on docs.microsoft.com. An application sends the WM\_WININICHANGE message to all top-level windows after making a change to the WIN.INI file. The SystemParametersInfo function sends this message after an application uses the function to change a setting in WIN.INI. Type: **LRESULT** If you process this message, return zero. To send the **WM\_WININICHANGE** message to all top-level windows, use the [**SendMessage**](/windows/win32/api/winuser/nf-winuser-sendmessage) function with the *hWnd* parameter set to **HWND\_BROADCAST**. Calls to functions that change WIN.INI may be mapped to the registry instead. This mapping occurs when WIN.INI and the section being changed are specified in the registry under the following key: **HKEY\_LOCAL\_MACHINE\\Software\\Microsoft\\Windows NT\\CurrentVersion\\IniFileMapping** The change in the storage location has no effect on the behavior of this message. Read more on docs.microsoft.com. A message that is sent to all top-level windows when the SystemParametersInfo function changes a system-wide setting or when policy settings have changed. Type: **LRESULT** If you process this message, return zero. The *lParam* parameter indicates which system metric has changed, for example, "ConvertibleSlateMode" if the CONVERTIBLESLATEMODE indicator was toggled or "SystemDockMode" if the DOCKED indicator was toggled. The WM\_DEVMODECHANGE message is sent to all top-level windows whenever the user changes device-mode settings. An application should return zero if it processes this message. This message cannot be sent directly to a window. To send the **WM\_DEVMODECHANGE** message to all top-level windows, use the [**SendMessageTimeout**](/windows/win32/api/winuser/nf-winuser-sendmessagetimeouta) function with the *hWnd* parameter set to HWND\_BROADCAST. Sent when a window belonging to a different application than the active window is about to be activated. The message is sent to the application whose window is being activated and to the application whose window is being deactivated. Type: **LRESULT** If an application processes this message, it should return zero. Learn more about this API from docs.microsoft.com. An application sends the WM\_FONTCHANGE message to all top-level windows in the system after changing the pool of font resources. An application that adds or removes fonts from the system (for example, by using the [**AddFontResource**](/windows/desktop/api/Wingdi/nf-wingdi-addfontresourcea) or [**RemoveFontResource**](/windows/desktop/api/Wingdi/nf-wingdi-removefontresourcea) function) should send this message to all top-level windows. To send the **WM\_FONTCHANGE** message to all top-level windows, an application can call the **SendMessage** function with the *hwnd* parameter set to HWND\_BROADCAST. Read more on docs.microsoft.com. A message that is sent whenever there is a change in the system time. An application should return zero if it processes this message. An application should not broadcast this message, because the system will broadcast this message when the application changes the system time. Sent to cancel certain modes, such as mouse capture. Type: **LRESULT** If an application processes this message, it should return zero. When the **WM\_CANCELMODE** message is sent, the [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function cancels internal processing of standard scroll bar input, cancels internal menu processing, and releases the mouse capture. Sent to a window if the mouse causes the cursor to move within a window and mouse input is not captured. If an application processes this message, it should return **TRUE** to halt further processing or **FALSE** to continue. The [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowprocw) function passes the **WM\_SETCURSOR** message to a parent window before processing. If the parent window returns **TRUE**, further processing is halted. Passing the message to a window's parent window gives the parent window control over the cursor's setting in a child window. The **DefWindowProc** function also uses this message to set the cursor to an arrow if it is not in the client area, or to the registered class cursor if it is in the client area. If the low-order word of the *lParam* parameter is **HTERROR** and the high-order word of *lParam* specifies that one of the mouse buttons is pressed, **DefWindowProc** calls the [**MessageBeep**](/windows/desktop/api/winuser/nf-winuser-messagebeep) function. Sent when the cursor is in an inactive window and the user presses a mouse button. The parent window receives this message only if the child window passes it to the DefWindowProc function. The return value specifies whether the window should be activated and whether the identifier of the mouse message should be discarded. It must be one of the following values. | Return code/value | Description | |------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------| |
**MA\_ACTIVATE**
1
| Activates the window, and does not discard the mouse message.
| |
**MA\_ACTIVATEANDEAT**
2
| Activates the window, and discards the mouse message.
| |
**MA\_NOACTIVATE**
3
| Does not activate the window, and does not discard the mouse message.
| |
**MA\_NOACTIVATEANDEAT**
4
| Does not activate the window, but discards the mouse message.
| The [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function passes the message to a child window's parent window before any processing occurs. The parent window determines whether to activate the child window. If it activates the child window, the parent window should return **MA\_NOACTIVATE** or **MA\_NOACTIVATEANDEAT** to prevent the system from processing the message further. Sent to a child window when the user clicks the window's title bar or when the window is activated, moved, or sized. Type: **LRESULT** If an application processes this message, it should return zero. Learn more about this API from docs.microsoft.com. Sent by a computer-based training (CBT) application to separate user-input messages from other messages sent through the WH\_JOURNALPLAYBACK procedure. Type: **void** A CBT application should return zero if it processes this message. Whenever a CBT application uses the [**WH\_JOURNALPLAYBACK**](about-hooks.md) procedure, the first and last messages are **WM\_QUEUESYNC**. This allows the CBT application to intercept and examine user-initiated messages without doing so for events that it sends. If an application specifies a **NULL** window handle, the message is posted to the message queue of the active window. Read more on docs.microsoft.com. Sent to a window when the size or position of the window is about to change. An application can use this message to override the window's default maximized size and position, or its default minimum or maximum tracking size. Type: **LRESULT** If an application processes this message, it should return zero. The maximum tracking size is the largest window size that can be produced by using the borders to size the window. The minimum tracking size is the smallest window size that can be produced by using the borders to size the window. Sent to a dialog box procedure to set the keyboard focus to a different control in the dialog box. An application should return zero if it processes this message. This message performs additional dialog box management operations beyond those performed by the [**SetFocus**](/windows/desktop/api/winuser/nf-winuser-setfocus) function **WM\_NEXTDLGCTL** updates the default pushbutton border, sets the default control identifier, and automatically selects the text of an edit control (if the target window is an edit control). Do not use the [**SendMessage**](/windows/desktop/api/winuser/nf-winuser-sendmessage) function to send a **WM\_NEXTDLGCTL** message if your application will concurrently process other messages that set the focus. Use the [**PostMessage**](/windows/desktop/api/winuser/nf-winuser-postmessagea) function instead. Read more on docs.microsoft.com. The WM\_SPOOLERSTATUS message is sent from Print Manager whenever a job is added to or removed from the Print Manager queue. An application should return zero if it processes this message. This message is for informational purposes only. This message is advisory and does not have guaranteed delivery semantics. Applications should not assume that they will receive a WM\_SPOOLERSTATUS message for every change in spooler status. The WM\_SPOOLERSTATUS message is not supported after Windows XP. To be notified of changes to the print queue status, you can use [**FindFirstPrinterChangeNotification**](findfirstprinterchangenotification.md) and [**FindNextPrinterChangeNotification**](findnextprinterchangenotification.md). Read more on docs.microsoft.com. Sent to the parent window of an owner-drawn button, combo box, list box, or menu when a visual aspect of the button, combo box, list box, or menu has changed. If an application processes this message, it should return **TRUE**. By default, the [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function draws the focus rectangle for an owner-drawn list box item. The *itemAction* member of the [**DRAWITEMSTRUCT**](/windows/win32/api/winuser/ns-winuser-drawitemstruct) structure specifies the drawing operation that an application should perform. Before returning from processing this message, an application should ensure that the device context identified by the *hDC* member of the [**DRAWITEMSTRUCT**](/windows/win32/api/winuser/ns-winuser-drawitemstruct) structure is in the default state. Read more on docs.microsoft.com. Sent to the owner window of a combo box, list box, list-view control, or menu item when the control or menu is created. If an application processes this message, it should return **TRUE**. When the owner window receives the **WM\_MEASUREITEM** message, the owner fills in the [**MEASUREITEMSTRUCT**](/windows/win32/api/winuser/ns-winuser-measureitemstruct) structure pointed to by the *lParam* parameter of the message and returns; this informs the system of the dimensions of the control. If a list box or combo box is created with the [**LBS\_OWNERDRAWVARIABLE**](list-box-styles.md) or [**CBS\_OWNERDRAWVARIABLE**](combo-box-styles.md) style, this message is sent to the owner for each item in the control; otherwise, this message is sent once. The system sends the **WM\_MEASUREITEM** message to the owner window of combo boxes and list boxes created with the OWNERDRAWFIXED style before sending the [**WM\_INITDIALOG**](/windows/desktop/dlgbox/wm-initdialog) message. As a result, when the owner receives this message, the system has not yet determined the height and width of the font used in the control; function calls and calculations requiring these values should occur in the main function of the application or library. Read more on docs.microsoft.com. Sent to the owner of a list box or combo box when the list box or combo box is destroyed or when items are removed by the LB\_DELETESTRING, LB\_RESETCONTENT, CB\_DELETESTRING, or CB\_RESETCONTENT message. An application should return **TRUE** if it processes this message. Microsoft Windows NT and later: Windows sends a **WM\_DELETEITEM** message only for items deleted from an owner-drawn list box (with the [**LBS\_OWNERDRAWFIXED**](list-box-styles.md) or [**LBS\_OWNERDRAWVARIABLE**](list-box-styles.md) style) or owner-drawn combo box (with the [**CBS\_OWNERDRAWFIXED**](combo-box-styles.md) or [**CBS\_OWNERDRAWVARIABLE**](combo-box-styles.md) style). Windows 95: Windows sends the **WM\_DELETEITEM** message for any deleted list box or combo box item with nonzero item data. Read more on docs.microsoft.com. Sent by a list box with the LBS\_WANTKEYBOARDINPUT style to its owner in response to a WM\_KEYDOWN message. The return value specifies the action that the application performed in response to the message. A return value of -2 indicates that the application handled all aspects of selecting the item and requires no further action by the list box. (See Remarks.) A return value of -1 indicates that the list box should perform the default action in response to the keystroke. A return value of 0 or greater specifies the index of an item in the list box and indicates that the list box should perform the default action for the keystroke on the specified item. A return value of -2 is valid only for keys that are not translated into characters by the list box control. If the [**WM\_KEYDOWN**](/windows/desktop/inputdev/wm-keydown) message translates to a [**WM\_CHAR**](/windows/desktop/inputdev/wm-char) message and the application processes the **WM\_VKEYTOITEM** message generated as a result of the key press, the list box ignores the return value and does the default processing for that character). **WM\_KEYDOWN** messages generated by keys such as VK\_UP, VK\_DOWN, VK\_NEXT, and VK\_PREVIOUS are not translated to **WM\_CHAR** messages. In such cases, trapping the **WM\_VKEYTOITEM** message and returning -2 prevents the list box from doing the default processing for that key. To trap keys that generate a char message and do special processing, the application must subclass the list box, trap both the [**WM\_KEYDOWN**](/windows/desktop/inputdev/wm-keydown) and [**WM\_CHAR**](/windows/desktop/inputdev/wm-char) messages, and process the messages appropriately in the subclass procedure. The preceding remarks apply to regular list boxes that are created with the [**LBS\_WANTKEYBOARDINPUT**](list-box-styles.md) style. If the list box is owner-drawn, the application must process the [**WM\_CHARTOITEM**](wm-chartoitem.md) message. The [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function returns -1. If a dialog box procedure handles this message, it should cast the desired return value to a **BOOL** and return the value directly. The DWL\_MSGRESULT value set by the [**SetWindowLong**](/windows/desktop/api/winuser/nf-winuser-setwindowlonga) function is ignored. Read more on docs.microsoft.com. Sent by a list box with the LBS\_WANTKEYBOARDINPUT style to its owner in response to a WM\_CHAR message. The return value specifies the action that the application performed in response to the message. A return value of -1 or -2 indicates that the application handled all aspects of selecting the item and requires no further action by the list box. A return value of 0 or greater specifies the zero-based index of an item in the list box and indicates that the list box should perform the default action for the keystroke on the specified item. The [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function returns -1. Only owner-drawn list boxes that do not have the [**LBS\_HASSTRINGS**](list-box-styles.md) style can receive this message. If a dialog box procedure handles this message, it should cast the desired return value to a **BOOL** and return the value directly. The *DWL\_MSGRESULT* value set by the [**SetWindowLong**](/windows/desktop/api/winuser/nf-winuser-setwindowlonga) function is ignored. Read more on docs.microsoft.com. Sets the font that a control is to use when drawing text. Type: **LRESULT** This message does not return a value. The **WM\_SETFONT** message applies to all controls, not just those in dialog boxes. The best time for the owner of a dialog box control to set the font of the control is when it receives the [**WM\_INITDIALOG**](../dlgbox/wm-initdialog.md) message. The application should call the [**DeleteObject**](/windows/win32/api/wingdi/nf-wingdi-deleteobject) function to delete the font when it is no longer needed; for example, after it destroys the control. The size of the control does not change as a result of receiving this message. To avoid clipping text that does not fit within the boundaries of the control, the application should correct the size of the control window before it sets the font. When a dialog box uses the [DS\_SETFONT](../dlgbox/about-dialog-boxes.md) style to set the text in its controls, the system sends the **WM\_SETFONT** message to the dialog box procedure before it creates the controls. An application can create a dialog box that contains the DS\_SETFONT style by calling any of the following functions: - [**CreateDialogIndirect**](/windows/win32/api/winuser/nf-winuser-createdialogindirecta) - [**CreateDialogIndirectParam**](/windows/win32/api/winuser/nf-winuser-createdialogindirectparama) - [**DialogBoxIndirect**](/windows/win32/api/winuser/nf-winuser-dialogboxindirecta) - [**DialogBoxIndirectParam**](/windows/win32/api/winuser/nf-winuser-dialogboxindirectparama) Read more on docs.microsoft.com. Retrieves the font with which the control is currently drawing its text. Type: **HFONT** The return value is a handle to the font used by the control, or **NULL** if the control is using the system font. Learn more about this API from docs.microsoft.com. Sent to a window to associate a hot key with the window. When the user presses the hot key, the system activates the window. The return value is one of the following. | Return value | Description | |-------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------| |
-1
| The function is unsuccessful; the hot key is invalid.
| |
0
| The function is unsuccessful; the window is invalid.
| |
1
| The function is successful, and no other window has the same hot key.
| |
2
| The function is successful, but another window already has the same hot key.
| A hot key cannot be associated with a child window. **VK\_ESCAPE**, **VK\_SPACE**, and **VK\_TAB** are invalid hot keys. When the user presses the hot key, the system generates a [**WM\_SYSCOMMAND**](/windows/desktop/menurc/wm-syscommand) message with *wParam* equal to **SC\_HOTKEY** and *lParam* equal to the window's handle. If this message is passed on to [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca), the system will bring the window's last active popup (if it exists) or the window itself (if there is no popup window) to the foreground. A window can only have one hot key. If the window already has a hot key associated with it, the new hot key replaces the old one. If more than one window has the same hot key, the window that is activated by the hot key is random. These hot keys are unrelated to the hot keys set by [**RegisterHotKey**](/windows/win32/api/winuser/nf-winuser-registerhotkey). Read more on docs.microsoft.com. Sent to determine the hot key associated with a window. The return value is the virtual-key code and modifiers for the hot key, or **NULL** if no hot key is associated with the window. The virtual-key code is in the low byte of the return value and the modifiers are in the high byte. The modifiers can be a combination of the following flags from CommCtrl.h. | Return code/value | Description | |-----------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------| |
**HOTKEYF\_ALT**
0x04
| ALT key
| |
**HOTKEYF\_CONTROL**
0x02
| CTRL key
| |
**HOTKEYF\_EXT**
0x08
| Extended key
| |
**HOTKEYF\_SHIFT**
0x01
| SHIFT key
| These hot keys are unrelated to the hot keys set by the [**RegisterHotKey**](/windows/win32/api/winuser/nf-winuser-registerhotkey) function. Sent to a minimized (iconic) window. Type: **LRESULT** An application should return a handle to a cursor or icon that the system is to display while the user drags the icon. The cursor or icon must be compatible with the display driver's resolution. If the application returns **NULL**, the system displays the default cursor. When the user drags the icon of a window without a class icon, the system replaces the icon with a default cursor. If the application requires a different cursor to be displayed during dragging, it must return a handle to the cursor or icon compatible with the display driver's resolution. If an application returns a handle to a color cursor or icon, the system converts the cursor or icon to black and white. The application can call the [**LoadCursor**](/windows/win32/api/winuser/nf-winuser-loadcursora) or [**LoadIcon**](/windows/win32/api/winuser/nf-winuser-loadicona) function to load a cursor or icon from the resources in its executable (.exe) file and to retrieve this handle. If a dialog box procedure handles this message, it should cast the desired return value to a **BOOL** and return the value directly. The **DWL\_MSGRESULT** value set by the [**SetWindowLong**](/windows/win32/api/winuser/nf-winuser-setwindowlonga) function is ignored. Read more on docs.microsoft.com. Sent to determine the relative position of a new item in the sorted list of an owner-drawn combo box or list box. The return value indicates the relative position of the two items. It may be any of the values shown in the following table. | Return code | Description | |--------------------------------------------------------------------------------------|--------------------------------------------------------------| |
**Value**
| Meaning
| |
**-1**
| Item 1 precedes item 2 in the sorted order.
| |
**0**
| Items 1 and 2 are equivalent in the sorted order.
| |
**1**
| Item 1 follows item 2 in the sorted order.
| When the owner of an owner-drawn combo box or list box receives this message, the owner returns a value indicating which of the items specified by the [**COMPAREITEMSTRUCT**](/windows/win32/api/winuser/ns-winuser-compareitemstruct) structure will appear before the other. Typically, the system sends this message several times until it determines the exact position for the new item. If a dialog box procedure handles this message, it should cast the desired return value to a **BOOL** and return the value directly. The DWL\_MSGRESULT value set by the [**SetWindowLong**](/windows/desktop/api/winuser/nf-winuser-setwindowlonga) function is ignored. Read more on docs.microsoft.com. Sent by both Microsoft Active Accessibility and Microsoft UI Automation to obtain information about an accessible object contained in a server application. If the window or control does not need to respond to this message, it should pass the message to the [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function; otherwise, the window or control should return a value that corresponds to the request specified by *dwObjId*: - If the window or control implements UI Automation, the window or control should return the value obtained by a call to the [**UiaReturnRawElementProvider**](/windows/desktop/api/UIAutomationCoreApi/nf-uiautomationcoreapi-uiareturnrawelementprovider) function. - If *dwObjId* is [**OBJID\_NATIVEOM**](object-identifiers.md) and the window exposes a native Object Model, the windows should return the value obtained by a call to the [**LresultFromObject**](/windows/desktop/api/Oleacc/nf-oleacc-lresultfromobject) function. - If *dwObjId* is [**OBJID\_CLIENT**](object-identifiers.md) and the window implements [**IAccessible**](/windows/desktop/api/oleacc/nn-oleacc-iaccessible), the window should return the value obtained by a call to the [**LresultFromObject**](/windows/desktop/api/Oleacc/nf-oleacc-lresultfromobject) function. When a client calls [**AccessibleObjectFromWindow**](/windows/desktop/api/Oleacc/nf-oleacc-accessibleobjectfromwindow) or any of the other **AccessibleObjectFrom***X* functions that retrieve an interface to an object, Microsoft Active Accessibility sends the **WM\_GETOBJECT** message to the appropriate window procedure within the appropriate server application. While processing **WM\_GETOBJECT**, server applications call [**LresultFromObject**](/windows/desktop/api/Oleacc/nf-oleacc-lresultfromobject) and use the return value of this function as the return value for the message. Microsoft Active Accessibility, in conjunction with the COM library, performs the appropriate marshaling and passes the interface pointer from the server back to the client. Servers do not respond to **WM\_GETOBJECT** before the object is fully initialized or after it begins to close down. When an application creates a new window, the system sends [**EVENT\_OBJECT\_CREATE**](event-constants.md) to notify clients before it sends the [WM\_CREATE](../winmsg/wm-create.md) message to the application's window procedure. Because many applications use WM\_CREATE to start their initialization process, servers do not respond to the **WM\_GETOBJECT** message until finished processing the **WM\_CREATE** message. A server uses **WM\_GETOBJECT** to perform the following tasks: - [Create New Accessible Objects](create-new-accessible-objects.md) - [Reuse Existing Pointers to Objects](reuse-existing-pointers-to-objects.md) - [Create New Interfaces to the Same Object](create-new-interfaces-to-the-same-object.md) For clients, this means that they might receive distinct interface pointers for the same user interface element, depending on the server's action. To determine if two interface pointers point to the same user interface element, clients compare [**IAccessible**](/windows/desktop/api/oleacc/nn-oleacc-iaccessible) properties of the object. Comparing pointers does not work. Read more on docs.microsoft.com. Sent to all top-level windows when the system detects more than 12.5 percent of system time over a 30- to 60-second interval is being spent compacting memory. This indicates that system memory is low. Type: **LRESULT** If an application processes this message, it should return zero. When an application receives this message, it should free as much memory as possible, taking into account the current level of activity of the application and the total number of applications running on the system. Sent to a window whose size, position, or place in the Z order is about to change as a result of a call to the SetWindowPos function or another window-management function. Type: **LRESULT** If an application processes this message, it should return zero. For a window with the [**WS\_OVERLAPPED**](window-styles.md) or **WS\_THICKFRAME** style, the [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function sends the [**WM\_GETMINMAXINFO**](wm-getminmaxinfo.md) message to the window. This is done to validate the new size and position of the window and to enforce the [CS\_BYTEALIGNCLIENT](about-window-classes.md) and CS\_BYTEALIGNWINDOW client styles. By not passing the **WM\_WINDOWPOSCHANGING** message to the **DefWindowProc** function, an application can override these defaults. While this message is being processed, modifying any of the values in [**WINDOWPOS**](/windows/win32/api/winuser/ns-winuser-windowpos) affects the window's new size, position, or place in the Z order. An application can prevent changes to the window by setting or clearing the appropriate bits in the **flags** member of **WINDOWPOS**. Read more on docs.microsoft.com. Sent to a window whose size, position, or place in the Z order has changed as a result of a call to the SetWindowPos function or another window-management function. Type: **LRESULT** If an application processes this message, it should return zero. By default, the [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function sends the [**WM\_SIZE**](wm-size.md) and [**WM\_MOVE**](wm-move.md) messages to the window. The **WM\_SIZE** and **WM\_MOVE** messages are not sent if an application handles the **WM\_WINDOWPOSCHANGED** message without calling **DefWindowProc**. It is more efficient to perform any move or size change processing during the **WM\_WINDOWPOSCHANGED** message without calling **DefWindowProc**. Notifies applications that the system, typically a battery-powered personal computer, is about to enter a suspended mode. The value an application returns depends on the value of the *wParam* parameter. If *wParam* is **PWR\_SUSPENDREQUEST**, the return value is **PWR\_FAIL** to prevent the system from entering the suspended state; otherwise, it is **PWR\_OK**. If *wParam* is **PWR\_SUSPENDRESUME** or **PWR\_CRITICALRESUME**, the return value is zero. This message is broadcast only to an application that is running on a system that conforms to the Advanced Power Management (APM) basic input/output system (BIOS) specification. The message is broadcast by the power-management driver to each window returned by the **EnumWindows** function. The suspended mode is the state in which the greatest amount of power savings occurs, but all operational data and parameters are preserved. Random-access memory (RAM) contents are preserved, but many devices are likely to be turned off. Read more on docs.microsoft.com. An application sends the WM\_COPYDATA message to pass data to another application. If the receiving application processes this message, it should return **TRUE**; otherwise, it should return **FALSE**. The data being passed must not contain pointers or other references to objects not accessible to the application receiving the data. While this message is being sent, the referenced data must not be changed by another thread of the sending process. The receiving application should consider the data read-only. The *lParam* parameter is valid only during the processing of the message. The receiving application should not free the memory referenced by *lParam*. If the receiving application must access the data after [**SendMessage**](/windows/desktop/api/winuser/nf-winuser-sendmessage) returns, it must copy the data into a local buffer. Read more on docs.microsoft.com. Posted to an application when a user cancels the application's journaling activities. The message is posted with a NULL window handle. Type: **void** This message does not return a value. It is meant to be processed from within an application's main loop or a [**GetMessage**](/windows/win32/api/winuser/nf-winuser-getmessage) hook procedure, not from a window procedure. Journal record and playback modes are modes imposed on the system that let an application sequentially record or play back user input. The system enters these modes when an application installs a [*JournalRecordProc*](/previous-versions/windows/desktop/legacy/ms644983(v=vs.85)) or [*JournalPlaybackProc*](/previous-versions/windows/desktop/legacy/ms644982(v=vs.85)) hook procedure. When the system is in either of these journaling modes, applications must take turns reading input from the input queue. If any one application stops reading input while the system is in a journaling mode, other applications are forced to wait. To ensure a robust system, one that cannot be made unresponsive by any one application, the system automatically cancels any journaling activities when a user presses CTRL+ESC or CTRL+ALT+DEL. The system then unhooks any journaling hook procedures, and posts a **WM\_CANCELJOURNAL** message, with a **NULL** window handle, to the application that set the journaling hook. The **WM\_CANCELJOURNAL** message has a **NULL** window handle, therefore it cannot be dispatched to a window procedure. There are two ways for an application to see a **WM\_CANCELJOURNAL** message: If the application is running in its own main loop, it must catch the message between its call to [**GetMessage**](/windows/win32/api/winuser/nf-winuser-getmessage) or [**PeekMessage**](/windows/win32/api/winuser/nf-winuser-peekmessagea) and its call to [**DispatchMessage**](/windows/win32/api/winuser/nf-winuser-dispatchmessage). If the application is not running in its own main loop, it must set a [*GetMsgProc*](/previous-versions/windows/desktop/legacy/ms644981(v=vs.85)) hook procedure (through a call to [**SetWindowsHookEx**](/windows/win32/api/winuser/nf-winuser-setwindowshookexa) specifying the **WH\_GETMESSAGE** hook type) that watches for the message. When an application sees a **WM\_CANCELJOURNAL** message, it can assume two things: the user has intentionally canceled the journal record or playback mode, and the system has already unhooked any journal record or playback hook procedures. Note that the key combinations mentioned above (CTRL+ESC or CTRL+ALT+DEL) cause the system to cancel journaling. If any one application is made unresponsive, they give the user a means of recovery. The [**VK\_CANCEL**](../inputdev/virtual-key-codes.md) virtual key code (usually implemented as the CTRL+BREAK key combination) is what an application that is in journal record mode should watch for as a signal that the user wishes to cancel the journaling activity. The difference is that watching for **VK\_CANCEL** is a suggested behavior for journaling applications, whereas CTRL+ESC or CTRL+ALT+DEL cause the system to cancel journaling regardless of a journaling application's behavior. Read more on docs.microsoft.com. Posted to the window with the focus when the user chooses a new input language, either with the hotkey (specified in the Keyboard control panel application) or from the indicator on the system taskbar. Type: **LRESULT** This message is posted, not sent, to the application, so the return value is ignored. To accept the change, the application should pass the message to [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca). To reject the change, the application should return zero without calling **DefWindowProc**. When the [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function receives the **WM\_INPUTLANGCHANGEREQUEST** message, it activates the new input locale and notifies the application of the change by sending the [**WM\_INPUTLANGCHANGE**](wm-inputlangchange.md) message. The language indicator is present on the taskbar only if you have installed more than one keyboard layout and if you have enabled the indicator using the Keyboard control panel application. Read more on docs.microsoft.com. Sent to the topmost affected window after an application's input language has been changed. You should make any application-specific settings and pass the message to the DefWindowProc function, which passes the message to all first-level child windows. Type: **LRESULT** An application should return nonzero if it processes this message. You can retrieve the [BCP 47](https://www.rfc-editor.org/info/bcp47) [locale name](../Intl/locale-names.md) from the language identifier by calling the [LCIDToLocaleName](/windows/win32/api/winnls/nf-winnls-lcidtolocalename) function. Once you have the locale name, you can then use [modern locale functions](/windows/win32/intl/calling-the--locale-name--functions) to extract additional locale information. This doc was truncated. Read more on docs.microsoft.com. Sent to an application that has initiated a training card with Windows Help. The return value is ignored; use zero. Learn more about this API from docs.microsoft.com. Indicates that the user pressed the F1 key. Returns **TRUE**. The [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function passes **WM\_HELP** to the parent window of a child window or to the owner of a top-level window. Sent to all windows after the user has logged on or off. When the user logs on or off, the system updates the user-specific settings. The system sends this message immediately after updating the settings. Type: **LRESULT** An application should return zero if it processes this message. Learn more about this API from docs.microsoft.com. Determines if a window accepts ANSI or Unicode structures in the WM\_NOTIFY notification message. WM\_NOTIFYFORMAT messages are sent from a common control to its parent window and from the parent window to the common control. Returns one of the following values. | Return code | Description | |---------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------| |
**NFR\_ANSI**
| ANSI structures should be used in [**WM\_NOTIFY**](wm-notify.md) messages sent by the control.
| |
**NFR\_UNICODE**
| Unicode structures should be used in [**WM\_NOTIFY**](wm-notify.md) messages sent by the control.
| |
**0**
| An error occurred.
| When a common control is created, the control sends a **WM\_NOTIFYFORMAT** message to its parent window to determine the type of structures to use in [**WM\_NOTIFY**](wm-notify.md) messages. If the parent window does not handle this message, the [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function responds according to the type of the parent window. That is, if the parent window is a Unicode window, **DefWindowProc** returns NFR\_UNICODE, and if the parent window is an ANSI window, **DefWindowProc** returns NFR\_ANSI. If the parent window is a dialog box and does not handle this message, the [**DefDlgProc**](/windows/desktop/api/winuser/nf-winuser-defdlgprocw) function similarly responds according to the type of the dialog box (Unicode or ANSI). A parent window can change the type of structures a common control uses in [**WM\_NOTIFY**](wm-notify.md) messages by setting *lParam* to NF\_REQUERY and sending a **WM\_NOTIFYFORMAT** message to the control. This causes the control to send an NF\_QUERY form of the **WM\_NOTIFYFORMAT** message to the parent window. All common controls will send **WM\_NOTIFYFORMAT** messages. However, the standard Windows controls (edit controls, combo boxes, list boxes, buttons, scroll bars, and static controls) do not. Read more on docs.microsoft.com. Sent to a window when the SetWindowLong function is about to change one or more of the window's styles. Type: **LRESULT** An application should return zero if it processes this message. Learn more about this API from docs.microsoft.com. Sent to a window after the SetWindowLong function has changed one or more of the window's styles. Type: **LRESULT** An application should return zero if it processes this message. Learn more about this API from docs.microsoft.com. The WM\_DISPLAYCHANGE message is sent to all windows when the display resolution has changed. This message is only sent to top-level windows. For all other windows it is posted. Sent to a window to retrieve a handle to the large or small icon associated with a window. The system displays the large icon in the ALT+TAB dialog, and the small icon in the window caption. Type: **HICON** The return value is a handle to the large or small icon, depending on the value of *wParam*. When an application receives this message, it can return a handle to a large or small icon, or pass the message to the [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function. When an application receives this message, it can return a handle to a large or small icon, or pass the message to [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca). [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) returns a handle to the large or small icon associated with the window, depending on the value of *wParam*. A window that has no icon explicitly set (with **WM\_SETICON**) uses the icon for the registered window class, and in this case [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) will return 0 for a **WM\_GETICON** message. If sending a **WM\_GETICON** message to a window returns 0, next try calling the [**GetClassLongPtr**](/windows/win32/api/winuser/nf-winuser-getclasslongptra) function for the window. If that returns 0 then try the [**LoadIcon**](/windows/win32/api/winuser/nf-winuser-loadicona) function. Read more on docs.microsoft.com. Associates a new large or small icon with a window. The system displays the large icon in the ALT+TAB dialog box, and the small icon in the window caption. Type: **LRESULT** The return value is a handle to the previous large or small icon, depending on the value of *wParam*. It is **NULL** if the window previously had no icon of the type indicated by *wParam*. The [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function returns a handle to the previous large or small icon associated with the window, depending on the value of *wParam*. Sent prior to the WM\_CREATE message when a window is first created. Type: **LRESULT** If an application processes this message, it should return **TRUE** to continue creation of the window. If the application returns **FALSE**, the [**CreateWindow**](/windows/win32/api/winuser/nf-winuser-createwindowa) or [**CreateWindowEx**](/windows/win32/api/winuser/nf-winuser-createwindowexa) function will return a **NULL** handle. Learn more about this API from docs.microsoft.com. Notifies a window that its nonclient area is being destroyed. The DestroyWindow function sends the WM\_NCDESTROY message to the window following the WM\_DESTROY message. Type: **LRESULT** If an application processes this message, it should return zero. This message frees any memory internally allocated for the window. Sent when the size and position of a window's client area must be calculated. By processing this message, an application can control the content of the window's client area when the size or position of the window changes. Type: **LRESULT** If the *wParam* parameter is **FALSE**, the application should return zero. If *wParam* is **TRUE**, the application should return zero or a combination of the following values. If *wParam* is **TRUE** and an application returns zero, the old client area is preserved and is aligned with the upper-left corner of the new client area. | Return code/value | Description | |-------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |
**WVR\_ALIGNTOP**
0x0010
| Specifies that the client area of the window is to be preserved and aligned with the top of the new position of the window. For example, to align the client area to the upper-left corner, return the WVR\_ALIGNTOP and **WVR\_ALIGNLEFT** values.
| |
**WVR\_ALIGNRIGHT**
0x0080
| Specifies that the client area of the window is to be preserved and aligned with the right side of the new position of the window. For example, to align the client area to the lower-right corner, return the **WVR\_ALIGNRIGHT** and WVR\_ALIGNBOTTOM values.
| |
**WVR\_ALIGNLEFT**
0x0020
| Specifies that the client area of the window is to be preserved and aligned with the left side of the new position of the window. For example, to align the client area to the lower-left corner, return the **WVR\_ALIGNLEFT** and **WVR\_ALIGNBOTTOM** values.
| |
**WVR\_ALIGNBOTTOM**
0x0040
| Specifies that the client area of the window is to be preserved and aligned with the bottom of the new position of the window. For example, to align the client area to the top-left corner, return the WVR\_ALIGNTOP and **WVR\_ALIGNLEFT** values.
| |
**WVR\_HREDRAW**
0x0100
| Used in combination with any other values, except **WVR\_VALIDRECTS**, causes the window to be completely redrawn if the client rectangle changes size horizontally. This value is similar to [CS\_HREDRAW](about-window-classes.md) class style
| |
**WVR\_VREDRAW**
0x0200
| Used in combination with any other values, except **WVR\_VALIDRECTS**, causes the window to be completely redrawn if the client rectangle changes size vertically. This value is similar to [CS\_VREDRAW](about-window-classes.md) class style
| |
**WVR\_REDRAW**
0x0300
| This value causes the entire window to be redrawn. It is a combination of **WVR\_HREDRAW** and **WVR\_VREDRAW** values.
| |
**WVR\_VALIDRECTS**
0x0400
| This value indicates that, upon return from [**WM\_NCCALCSIZE**](wm-nccalcsize.md), the rectangles specified by the **rgrc**\[1\] and **rgrc**\[2\] members of the [**NCCALCSIZE\_PARAMS**](/windows/win32/api/winuser/ns-winuser-nccalcsize_params) structure contain valid destination and source area rectangles, respectively. The system combines these rectangles to calculate the area of the window to be preserved. The system copies any part of the window image that is within the source rectangle and clips the image to the destination rectangle. Both rectangles are in parent-relative or screen-relative coordinates. This flag cannot be combined with any other flags.
This return value allows an application to implement more elaborate client-area preservation strategies, such as centering or preserving a subset of the client area.
| The window may be redrawn, depending on whether the [CS\_HREDRAW](about-window-classes.md) or CS\_VREDRAW class style is specified. This is the default, backward-compatible processing of this message by the [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function (in addition to the usual client rectangle calculation described in the preceding table). When *wParam* is **TRUE**, simply returning 0 without processing the [**NCCALCSIZE\_PARAMS**](/windows/win32/api/winuser/ns-winuser-nccalcsize_params) rectangles will cause the client area to resize to the size of the window, including the window frame. This will remove the window frame and caption items from your window, leaving only the client area displayed. Starting with Windows Vista, removing the standard frame by simply returning 0 when the *wParam* is **TRUE** does not affect frames that are extended into the client area using the [**DwmExtendFrameIntoClientArea**](/windows/win32/api/dwmapi/nf-dwmapi-dwmextendframeintoclientarea) function. Only the standard frame will be removed. Read more on docs.microsoft.com. Sent to a window in order to determine what part of the window corresponds to a particular screen coordinate. The return value of the [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function is one of the following values, indicating the position of the cursor hot spot. | Return code/value | Description | |------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |
**HTBORDER**
18
| In the border of a window that does not have a sizing border.
| |
**HTBOTTOM**
15
| In the lower-horizontal border of a resizable window (the user can click the mouse to resize the window vertically).
| |
**HTBOTTOMLEFT**
16
| In the lower-left corner of a border of a resizable window (the user can click the mouse to resize the window diagonally).
| |
**HTBOTTOMRIGHT**
17
| In the lower-right corner of a border of a resizable window (the user can click the mouse to resize the window diagonally).
| |
**HTCAPTION**
2
| In a title bar.
| |
**HTCLIENT**
1
| In a client area.
| |
**HTCLOSE**
20
| In a **Close** button.
| |
**HTERROR**
-2
| On the screen background or on a dividing line between windows (same as **HTNOWHERE**, except that the [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function produces a system beep to indicate an error).
| |
**HTGROWBOX**
4
| In a size box (same as **HTSIZE**).
| |
**HTHELP**
21
| In a **Help** button.
| |
**HTHSCROLL**
6
| In a horizontal scroll bar.
| |
**HTLEFT**
10
| In the left border of a resizable window (the user can click the mouse to resize the window horizontally).
| |
**HTMENU**
5
| In a menu.
| |
**HTMAXBUTTON**
9
| In a **Maximize** button.
| |
**HTMINBUTTON**
8
| In a **Minimize** button.
| |
**HTNOWHERE**
0
| On the screen background or on a dividing line between windows.
| |
**HTREDUCE**
8
| In a **Minimize** button.
| |
**HTRIGHT**
11
| In the right border of a resizable window (the user can click the mouse to resize the window horizontally).
| |
**HTSIZE**
4
| In a size box (same as **HTGROWBOX**).
| |
**HTSYSMENU**
3
| In a window menu or in a **Close** button in a child window.
| |
**HTTOP**
12
| In the upper-horizontal border of a window.
| |
**HTTOPLEFT**
13
| In the upper-left corner of a window border.
| |
**HTTOPRIGHT**
14
| In the upper-right corner of a window border.
| |
**HTTRANSPARENT**
-1
| In a window currently covered by another window in the same thread (the message will be sent to underlying windows in the same thread until one of them returns a code that is not **HTTRANSPARENT**).
| |
**HTVSCROLL**
7
| In the vertical scroll bar.
| |
**HTZOOM**
9
| In a **Maximize** button.
| Use the following code to obtain the horizontal and vertical position: This doc was truncated. Read more on docs.microsoft.com. The WM\_NCPAINT message is sent to a window when its frame must be painted. An application returns zero if it processes this message. The [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function paints the window frame. An application can intercept the **WM\_NCPAINT** message and paint its own custom window frame. The clipping region for a window is always rectangular, even if the shape of the frame is altered. The *wParam* value can be passed to [**GetDCEx**](/windows/desktop/api/Winuser/nf-winuser-getdcex) as in the following example. This doc was truncated. Read more on docs.microsoft.com. Sent to a window when its nonclient area needs to be changed to indicate an active or inactive state. Type: **LRESULT** When the *wParam* parameter is **FALSE**, an application should return **TRUE** to indicate that the system should proceed with the default processing, or it should return **FALSE** to prevent the change. When *wParam* is **TRUE**, the return value is ignored. Processing messages related to the nonclient area of a standard window is not recommended, because the application must be able to draw all the required parts of the nonclient area for the window. If an application does process this message, it must return **TRUE** to direct the system to complete the change of active window. If the window is minimized when this message is received, the application should pass the message to the [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function. The [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function draws the title bar or icon title in its active colors when the *wParam* parameter is **TRUE** and in its inactive colors when *wParam* is **FALSE**. Read more on docs.microsoft.com. Sent to the window procedure associated with a control. The return value is one or more of the following values, indicating which type of input the application processes. | Return code/value | Description | |------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------| |
**DLGC\_BUTTON**
0x2000
| Button.
| |
**DLGC\_DEFPUSHBUTTON**
0x0010
| Default push button.
| |
**DLGC\_HASSETSEL**
0x0008
| [**EM\_SETSEL**](/windows/desktop/Controls/em-setsel) messages.
| |
**DLGC\_RADIOBUTTON**
0x0040
| Radio button.
| |
**DLGC\_STATIC**
0x0100
| Static control.
| |
**DLGC\_UNDEFPUSHBUTTON**
0x0020
| Non-default push button.
| |
**DLGC\_WANTALLKEYS**
0x0004
| All keyboard input.
| |
**DLGC\_WANTARROWS**
0x0001
| Direction keys.
| |
**DLGC\_WANTCHARS**
0x0080
| [**WM\_CHAR**](/windows/desktop/inputdev/wm-char) messages.
| |
**DLGC\_WANTMESSAGE**
0x0004
| All keyboard input (the application passes this message in the [**MSG**](/windows/win32/api/winuser/ns-winuser-msg) structure to the control).
| |
**DLGC\_WANTTAB**
0x0002
| TAB key.
| Although the [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function always returns zero in response to the **WM\_GETDLGCODE** message, the window procedure for the predefined control classes return a code appropriate for each class. The **WM\_GETDLGCODE** message and the returned values are useful only with user-defined dialog box controls or standard controls modified by subclassing. Read more on docs.microsoft.com. The WM\_SYNCPAINT message is used to synchronize painting while avoiding linking independent GUI threads. An application returns zero if it processes this message. When a window has been hidden, shown, moved, or sized, the system may determine that it is necessary to send a **WM\_SYNCPAINT** message to the top-level windows of other threads. Applications must pass **WM\_SYNCPAINT** to [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) for processing. The **DefWindowProc** function will send a [**WM\_NCPAINT**](wm-ncpaint.md) message to the window procedure if the window frame must be painted and send a [**WM\_ERASEBKGND**](../winmsg/wm-erasebkgnd.md) message if the window background must be erased. Posted to a window when the cursor is moved within the nonclient area of the window. This message is posted to the window that contains the cursor. If a window has captured the mouse, this message is not posted. If an application processes this message, it should return zero. If it is appropriate to do so, the system sends the [**WM\_SYSCOMMAND**](/windows/desktop/menurc/wm-syscommand) message to the window. You can also use the [**GET\_X\_LPARAM**](/windows/desktop/api/windowsx/nf-windowsx-get_x_lparam) and [**GET\_Y\_LPARAM**](/windows/desktop/api/windowsx/nf-windowsx-get_y_lparam) macros to extract the values of the x- and y- coordinates from *lParam*. This doc was truncated. Read more on docs.microsoft.com. Posted when the user presses the left mouse button while the cursor is within the nonclient area of a window. This message is posted to the window that contains the cursor. If a window has captured the mouse, this message is not posted. If an application processes this message, it should return zero. The [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function tests the specified point to find the location of the cursor and performs the appropriate action. If appropriate, **DefWindowProc** sends the [**WM\_SYSCOMMAND**](/windows/desktop/menurc/wm-syscommand) message to the window. You can also use the [**GET\_X\_LPARAM**](/windows/desktop/api/windowsx/nf-windowsx-get_x_lparam) and [**GET\_Y\_LPARAM**](/windows/desktop/api/windowsx/nf-windowsx-get_y_lparam) macros to extract the values of the x- and y- coordinates from *lParam*. This doc was truncated. Read more on docs.microsoft.com. Posted when the user releases the left mouse button while the cursor is within the nonclient area of a window. This message is posted to the window that contains the cursor. If a window has captured the mouse, this message is not posted. If an application processes this message, it should return zero. The [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function tests the specified point to find out the location of the cursor and performs the appropriate action. If appropriate, **DefWindowProc** sends the [**WM\_SYSCOMMAND**](/windows/desktop/menurc/wm-syscommand) message to the window. You can also use the [**GET\_X\_LPARAM**](/windows/desktop/api/windowsx/nf-windowsx-get_x_lparam) and [**GET\_Y\_LPARAM**](/windows/desktop/api/windowsx/nf-windowsx-get_y_lparam) macros to extract the values of the x- and y- coordinates from *lParam*. This doc was truncated. Read more on docs.microsoft.com. Posted when the user double-clicks the left mouse button while the cursor is within the nonclient area of a window. This message is posted to the window that contains the cursor. If a window has captured the mouse, this message is not posted. If an application processes this message, it should return zero. You can also use the [**GET\_X\_LPARAM**](/windows/desktop/api/windowsx/nf-windowsx-get_x_lparam) and [**GET\_Y\_LPARAM**](/windows/desktop/api/windowsx/nf-windowsx-get_y_lparam) macros to extract the values of the x- and y- coordinates from *lParam*. This doc was truncated. Read more on docs.microsoft.com. Posted when the user presses the right mouse button while the cursor is within the nonclient area of a window. This message is posted to the window that contains the cursor. If a window has captured the mouse, this message is not posted. If an application processes this message, it should return zero. You can also use the [**GET\_X\_LPARAM**](/windows/desktop/api/windowsx/nf-windowsx-get_x_lparam) and [**GET\_Y\_LPARAM**](/windows/desktop/api/windowsx/nf-windowsx-get_y_lparam) macros to extract the values of the x- and y- coordinates from *lParam*. This doc was truncated. Read more on docs.microsoft.com. Posted when the user releases the right mouse button while the cursor is within the nonclient area of a window. This message is posted to the window that contains the cursor. If a window has captured the mouse, this message is not posted. If an application processes this message, it should return zero. You can also use the [**GET\_X\_LPARAM**](/windows/desktop/api/windowsx/nf-windowsx-get_x_lparam) and [**GET\_Y\_LPARAM**](/windows/desktop/api/windowsx/nf-windowsx-get_y_lparam) macros to extract the values of the x- and y- coordinates from *lParam*. This doc was truncated. Read more on docs.microsoft.com. Posted when the user double-clicks the right mouse button while the cursor is within the nonclient area of a window. This message is posted to the window that contains the cursor. If a window has captured the mouse, this message is not posted. If an application processes this message, it should return zero. A window need not have the **CS\_DBLCLKS** style to receive **WM\_NCRBUTTONDBLCLK** messages. The system generates a **WM\_NCRBUTTONDBLCLK** message when the user presses, releases, and again presses the right mouse button within the system's double-click time limit. Double-clicking the right mouse button actually generates four messages: [**WM\_NCRBUTTONDOWN**](wm-ncrbuttondown.md), [**WM\_NCRBUTTONUP**](wm-ncrbuttonup.md), **WM\_NCRBUTTONDBLCLK**, and **WM\_NCRBUTTONUP** again. You can also use the [**GET\_X\_LPARAM**](/windows/desktop/api/windowsx/nf-windowsx-get_x_lparam) and [**GET\_Y\_LPARAM**](/windows/desktop/api/windowsx/nf-windowsx-get_y_lparam) macros to extract the values of the x- and y- coordinates from *lParam*. This doc was truncated. Read more on docs.microsoft.com. Posted when the user presses the middle mouse button while the cursor is within the nonclient area of a window. This message is posted to the window that contains the cursor. If a window has captured the mouse, this message is not posted. If an application processes this message, it should return zero. You can also use the [**GET\_X\_LPARAM**](/windows/desktop/api/windowsx/nf-windowsx-get_x_lparam) and [**GET\_Y\_LPARAM**](/windows/desktop/api/windowsx/nf-windowsx-get_y_lparam) macros to extract the values of the x- and y- coordinates from *lParam*. This doc was truncated. Read more on docs.microsoft.com. Posted when the user releases the middle mouse button while the cursor is within the nonclient area of a window. This message is posted to the window that contains the cursor. If a window has captured the mouse, this message is not posted. If an application processes this message, it should return zero. You can also use the [**GET\_X\_LPARAM**](/windows/desktop/api/windowsx/nf-windowsx-get_x_lparam) and [**GET\_Y\_LPARAM**](/windows/desktop/api/windowsx/nf-windowsx-get_y_lparam) macros to extract the values of the x- and y- coordinates from *lParam*. This doc was truncated. Read more on docs.microsoft.com. Posted when the user double-clicks the middle mouse button while the cursor is within the nonclient area of a window. This message is posted to the window that contains the cursor. If a window has captured the mouse, this message is not posted. If an application processes this message, it should return zero. A window need not have the **CS\_DBLCLKS** style to receive **WM\_NCMBUTTONDBLCLK** messages. The system generates a **WM\_NCMBUTTONDBLCLK** message when the user presses, releases, and again presses the middle mouse button within the system's double-click time limit. Double-clicking the middle mouse button actually generates four messages: [**WM\_NCMBUTTONDOWN**](wm-ncmbuttondown.md), [**WM\_NCMBUTTONUP**](wm-ncmbuttonup.md), **WM\_NCMBUTTONDBLCLK**, and **WM\_NCMBUTTONUP** again. You can also use the [**GET\_X\_LPARAM**](/windows/desktop/api/windowsx/nf-windowsx-get_x_lparam) and [**GET\_Y\_LPARAM**](/windows/desktop/api/windowsx/nf-windowsx-get_y_lparam) macros to extract the values of the x- and y- coordinates from *lParam*. This doc was truncated. Read more on docs.microsoft.com. Posted when the user presses the first or second X button while the cursor is in the nonclient area of a window. This message is posted to the window that contains the cursor. If a window has captured the mouse, this message is not posted. If an application processes this message, it should return **TRUE**. For more information about processing the return value, see the Remarks section. Use the following code to get the information in the *wParam* parameter. This doc was truncated. Read more on docs.microsoft.com. Posted when the user releases the first or second X button while the cursor is in the nonclient area of a window. This message is posted to the window that contains the cursor. If a window has captured the mouse, this message is not posted. If an application processes this message, it should return **TRUE**. For more information about processing the return value, see the Remarks section. Use the following code to get the information in the *wParam* parameter. This doc was truncated. Read more on docs.microsoft.com. Posted when the user double-clicks the first or second X button while the cursor is in the nonclient area of a window. This message is posted to the window that contains the cursor. If a window has captured the mouse, this message is not posted. If an application processes this message, it should return **TRUE**. For more information about processing the return value, see the Remarks section. Use the following code to get the information in the *wParam* parameter. This doc was truncated. Read more on docs.microsoft.com. Sent to the window that registered to receive raw input. A window receives this message through its WindowProc function. If an application processes this message, it should return zero. Learn more about this API from docs.microsoft.com. Sent to the window that is getting raw input. A window receives this message through its WindowProc function. If an application processes this message, it should return zero. Raw input is available only when the application calls [**RegisterRawInputDevices**](/windows/win32/api/winuser/nf-winuser-registerrawinputdevices) with valid device specifications. Posted to the window with the keyboard focus when a nonsystem key is pressed. A nonsystem key is a key that is pressed when the ALT key is not pressed. An application should return zero if it processes this message. If the F10 key is pressed, the [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function sets an internal flag. When **DefWindowProc** receives the [**WM\_KEYUP**](wm-keyup.md) message, the function checks whether the internal flag is set and, if so, sends a [**WM\_SYSCOMMAND**](/windows/desktop/menurc/wm-syscommand) message to the top-level window. The **WM\_SYSCOMMAND** parameter of the message is set to SC\_KEYMENU. Because of the autorepeat feature, more than one **WM\_KEYDOWN** message may be posted before a [**WM\_KEYUP**](wm-keyup.md) message is posted. The previous key state (bit 30) can be used to determine whether the **WM\_KEYDOWN** message indicates the first down transition or a repeated down transition. For enhanced 101- and 102-key keyboards, extended keys are the right ALT and CTRL keys on the main section of the keyboard; the INS, DEL, HOME, END, PAGE UP, PAGE DOWN, and arrow keys in the clusters to the left of the numeric keypad; and the divide (/) and ENTER keys in the numeric keypad. Other keyboards may support the extended-key bit in the *lParam* parameter. Applications must pass *wParam* to [**TranslateMessage**](/windows/desktop/api/winuser/nf-winuser-translatemessage) without altering it at all. Read more on docs.microsoft.com. Posted to the window with the keyboard focus when a nonsystem key is released. A nonsystem key is a key that is pressed when the ALT key is not pressed, or a keyboard key that is pressed when a window has the keyboard focus. An application should return zero if it processes this message. The [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function sends a [**WM\_SYSCOMMAND**](/windows/desktop/menurc/wm-syscommand) message to the top-level window if the F10 key or the ALT key was released. The *wParam* parameter of the message is set to SC\_KEYMENU. For enhanced 101- and 102-key keyboards, extended keys are the right ALT and CTRL keys on the main section of the keyboard; the INS, DEL, HOME, END, PAGE UP, PAGE DOWN, and arrow keys in the clusters to the left of the numeric keypad; and the divide (/) and ENTER keys in the numeric keypad. Other keyboards may support the extended-key bit in the *lParam* parameter. Applications must pass *wParam* to [**TranslateMessage**](/windows/desktop/api/winuser/nf-winuser-translatemessage) without altering it at all. Read more on docs.microsoft.com. Posted to the window with the keyboard focus when a WM\_KEYDOWN message is translated by the TranslateMessage function. The WM\_CHAR message contains the character code of the key that was pressed. An application should return zero if it processes this message. The **WM\_CHAR** message uses UTF-16 (16-bit Unicode Transformation Format) code units in its **wParam** if the Unicode version of the [**RegisterClass**](/windows/win32/api/winuser/nf-winuser-registerclassw) function was used to register the window class. Otherwise, the system provides characters in the current process code page, which can be set to UTF-8 in Windows Version 1903 (May 2019 Update) and newer. For more information, see [Registering Window Classes](/windows/win32/intl/registering-window-classes) and [Use UTF-8 code pages in Windows apps](/windows/apps/design/globalizing/use-utf8-code-page). Starting with Windows Vista, **WM\_CHAR** message can send [UTF-16 surrogate pairs](/windows/win32/intl/surrogates-and-supplementary-characters) to Unicode windows. Use the [IS_HIGH_SURROGATE](/windows/win32/api/Winnls/nf-winnls-is_high_surrogate), [IS_LOW_SURROGATE](/windows/win32/api/winnls/nf-winnls-is_low_surrogate), and [IS_SURROGATE_PAIR](/windows/win32/api/winnls/nf-winnls-is_surrogate_pair) macros to detect such cases, if necessary. There is not necessarily a one-to-one correspondence between keys pressed and character messages generated, and so the information in the high-order word of the *lParam* parameter is generally not useful to applications. The information in the high-order word applies only to the most recent [**WM\_KEYDOWN**](wm-keydown.md) message that precedes the posting of the **WM\_CHAR** message. For enhanced 101- and 102-key keyboards, extended keys are the right ALT and the right CTRL keys on the main section of the keyboard; the INS, DEL, HOME, END, PAGE UP, PAGE DOWN and arrow keys in the clusters to the left of the numeric keypad; and the divide (/) and ENTER keys in the numeric keypad. Some other keyboards may support the extended-key bit in the *lParam* parameter. The [**WM\_UNICHAR**](wm-unichar.md) message is the same as **WM\_CHAR**, except it uses UTF-32. It is designed to send or post Unicode characters to ANSI windows, and it can handle Unicode Supplementary Plane characters. Read more on docs.microsoft.com. Posted to the window with the keyboard focus when a WM\_KEYUP message is translated by the TranslateMessage function. An application should return zero if it processes this message. The **WM\_DEADCHAR** message typically is used by applications to give the user feedback about each key pressed. For example, an application can display the accent in the current character position without moving the caret. Because there is not necessarily a one-to-one correspondence between keys pressed and character messages generated, the information in the high-order word of the *lParam* parameter is generally not useful to applications. The information in the high-order word applies only to the most recent [**WM\_KEYDOWN**](wm-keydown.md) message that precedes the posting of the **WM\_DEADCHAR** message. For enhanced 101- and 102-key keyboards, extended keys are the right ALT and the right CTRL keys on the main section of the keyboard; the INS, DEL, HOME, END, PAGE UP, PAGE DOWN and arrow keys in the clusters to the left of the numeric keypad; and the divide (/) and ENTER keys in the numeric keypad. Some other keyboards may support the extended-key bit in the *lParam* parameter. Read more on docs.microsoft.com. Posted to the window with the keyboard focus when the user presses the F10 key (which activates the menu bar) or holds down the ALT key and then presses another key. An application should return zero if it processes this message. The [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function examines the specified key and generates a [**WM\_SYSCOMMAND**](/windows/desktop/menurc/wm-syscommand) message if the key is either TAB or ENTER. When the context code is zero, the message can be passed to the [**TranslateAccelerator**](/windows/desktop/api/winuser/nf-winuser-translateacceleratora) function, which will handle it as though it were a normal key message instead of a character-key message. This allows accelerator keys to be used with the active window even if the active window does not have the keyboard focus. Because of automatic repeat, more than one **WM\_SYSKEYDOWN** message may occur before a [**WM\_SYSKEYUP**](wm-syskeyup.md) message is sent. The previous key state (bit 30) can be used to determine whether the **WM\_SYSKEYDOWN** message indicates the first down transition or a repeated down transition. For enhanced 101- and 102-key keyboards, enhanced keys are the right ALT and CTRL keys on the main section of the keyboard; the INS, DEL, HOME, END, PAGE UP, PAGE DOWN, and arrow keys in the clusters to the left of the numeric keypad; and the divide (/) and ENTER keys in the numeric keypad. Other keyboards may support the extended-key bit in the *lParam* parameter. This message is also sent whenever the user presses the F10 key without the ALT key. Read more on docs.microsoft.com. Posted to the window with the keyboard focus when the user releases a key that was pressed while the ALT key was held down. An application should return zero if it processes this message. The [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function sends a [**WM\_SYSCOMMAND**](/windows/desktop/menurc/wm-syscommand) message to the top-level window if the F10 key or the ALT key was released. The *wParam* parameter of the message is set to **SC\_KEYMENU**. When the context code is zero, the message can be passed to the [**TranslateAccelerator**](/windows/desktop/api/winuser/nf-winuser-translateacceleratora) function, which will handle it as though it were a normal key message instead of a character-key message. This allows accelerator keys to be used with the active window even if the active window does not have the keyboard focus. For enhanced 101- and 102-key keyboards, extended keys are the right ALT and CTRL keys on the main section of the keyboard; the INS, DEL, HOME, END, PAGE UP, PAGE DOWN, and arrow keys in the clusters to the left of the numeric keypad; and the divide (/) and ENTER keys in the numeric keypad. Other keyboards may support the extended-key bit in the *lParam* parameter. For non-U.S. enhanced 102-key keyboards, the right ALT key is handled as a CTRL+ALT key. The following table shows the sequence of messages that result when the user presses and releases this key. | Message | Virtual-key code | |-----------------------------------|------------------| | [**WM\_KEYDOWN**](wm-keydown.md) | **VK\_CONTROL** | | [**WM\_KEYDOWN**](wm-keydown.md) | **VK\_MENU** | | [**WM\_KEYUP**](wm-keyup.md) | **VK\_CONTROL** | | **WM\_SYSKEYUP** | **VK\_MENU** | Read more on docs.microsoft.com. Posted to the window with the keyboard focus when a WM\_SYSKEYDOWN message is translated by the TranslateMessage function. An application should return zero if it processes this message. When the context code is zero, the message can be passed to the [**TranslateAccelerator**](/windows/desktop/api/Winuser/nf-winuser-translateacceleratora) function, which will handle it as though it were a standard key message instead of a system character-key message. This allows accelerator keys to be used with the active window even if the active window does not have the keyboard focus. For enhanced 101- and 102-key keyboards, extended keys are the right ALT and CTRL keys on the main section of the keyboard; the INS, DEL, HOME, END, PAGE UP, PAGE DOWN and arrow keys in the clusters to the left of the numeric keypad; the PRINT SCRN key; the BREAK key; the NUMLOCK key; and the divide (/) and ENTER keys in the numeric keypad. Other keyboards may support the extended-key bit in the parameter. Read more on docs.microsoft.com. Sent to the window with the keyboard focus when a WM\_SYSKEYDOWN message is translated by the TranslateMessage function. An application should return zero if it processes this message. For enhanced 101- and 102-key keyboards, extended keys are the right ALT and CTRL keys on the main section of the keyboard; the INS, DEL, HOME, END, PAGE UP, PAGE DOWN, and arrow keys in the clusters to the left of the numeric keypad; and the divide (/) and ENTER keys in the numeric keypad. Other keyboards may support the extended-key bit in the *lParam* parameter. Sent immediately before the IME generates the composition string as a result of a keystroke. A window receives this message through its WindowProc function. This message has no parameters. This message has no return value. This message is a notification to an IME window to open its composition window. An application should process this message if it displays composition characters itself. If an application has created an IME window, it should pass this message to that window. The [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function processes the message by passing it to the default IME window. Read more on docs.microsoft.com. Sent to an application when the IME ends composition. A window receives this message through its WindowProc function. This message has no parameters. This message has no return value. An application should process this message if it displays composition characters itself. If the application has created an IME window, it should pass this message to that window. The [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function processes this message by passing it to the default IME window. Read more on docs.microsoft.com. Sent to an application when the IME changes composition status as a result of a keystroke. A window receives this message through its WindowProc function. This message has no return value. An application should process this message if it displays composition characters itself. Otherwise, it should send the message to the IME window. If the application has created an IME window, it should pass this message to that window. The [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function processes this message by passing it to the default IME window. The IME window processes this message by updating its appearance based on the change flag specified. An application can call [**ImmGetCompositionString**](/windows/desktop/api/Imm/nf-imm-immgetcompositionstringa) to retrieve the new composition status. If none of the GCS\_ values are set, the message indicates that the current composition has been canceled and applications that draw the composition string should delete the string. Read more on docs.microsoft.com. Sent to the dialog box procedure immediately before a dialog box is displayed. Dialog box procedures typically use this message to initialize controls and carry out any other initialization tasks that affect the appearance of the dialog box. The dialog box procedure should return **TRUE** to direct the system to set the keyboard focus to the control specified by *wParam*. Otherwise, it should return **FALSE** to prevent the system from setting the default keyboard focus. The dialog box procedure should return the value directly. The **DWL\_MSGRESULT** value set by the [**SetWindowLong**](/windows/desktop/api/winuser/nf-winuser-setwindowlonga) function is ignored. The control to receive the default keyboard focus is always the first control in the dialog box that is visible, not disabled, and that has the **WS\_TABSTOP** style. When the dialog box procedure returns **TRUE**, the system checks the control to ensure that the procedure has not disabled it. If it has been disabled, the system sets the keyboard focus to the next control that is visible, not disabled, and has the **WS\_TABSTOP**. An application can return **FALSE** only if it has set the keyboard focus to one of the controls of the dialog box. Read more on docs.microsoft.com. Sent when the user selects a command item from a menu, when a control sends a notification message to its parent window, or when an accelerator keystroke is translated. If an application processes this message, it should return zero. Use of the *wParam* and *lParam* parameters are summarized here. | Message Source | wParam (high word) | wParam (low word) | lParam | |----------------|-----------------------------------|----------------------------------|------------------------------| | Menu | 0 | Menu identifier (IDM\_\*) | 0 | | Accelerator | 1 | Accelerator identifier (IDM\_\*) | 0 | | Control | Control-defined notification code | Control identifier | Handle to the control window | Read more on docs.microsoft.com. A window receives this message when the user chooses a command from the Window menu (formerly known as the system or control menu) or when the user chooses the maximize button, minimize button, restore button, or close button. An application should return zero if it processes this message. To obtain the position coordinates in screen coordinates, use the following code: This doc was truncated. Read more on docs.microsoft.com. Posted to the installing thread's message queue when a timer expires. The message is posted by the GetMessage or PeekMessage function. Type: **LRESULT** An application should return zero if it processes this message. You can process the message by providing a **WM\_TIMER** case in the window procedure. Otherwise, [**DispatchMessage**](/windows/win32/api/winuser/nf-winuser-dispatchmessage) will call the [*TimerProc*](/windows/win32/api/winuser/nc-winuser-timerproc) callback function specified in the call to the [**SetTimer**](/windows/win32/api/winuser/nf-winuser-settimer) function used to install the timer. The **WM\_TIMER** message is a low-priority message. The [**GetMessage**](/windows/win32/api/winuser/nf-winuser-getmessage) and [**PeekMessage**](/windows/win32/api/winuser/nf-winuser-peekmessagea) functions post this message only when no other higher-priority messages are in the thread's message queue. Read more on docs.microsoft.com. The WM\_HSCROLL message is sent to a window when a scroll event occurs in the window's standard horizontal scroll bar. If an application processes this message, it should return zero. The SB\_THUMBTRACK request code is typically used by applications that provide feedback as the user drags the scroll box. If an application scrolls the content of the window, it must also reset the position of the scroll box by using the [**SetScrollPos**](/windows/desktop/api/Winuser/nf-winuser-setscrollpos) function. Note that the **WM\_HSCROLL** message carries only 16 bits of scroll box position data. Thus, applications that rely solely on **WM\_HSCROLL** (and [**WM\_VSCROLL**](wm-vscroll.md)) for scroll position data have a practical maximum position value of 65,535. However, because the [**SetScrollInfo**](/windows/desktop/api/Winuser/nf-winuser-setscrollinfo), [**SetScrollPos**](/windows/desktop/api/Winuser/nf-winuser-setscrollpos), [**SetScrollRange**](/windows/desktop/api/Winuser/nf-winuser-setscrollrange), [**GetScrollInfo**](/windows/desktop/api/Winuser/nf-winuser-getscrollinfo), [**GetScrollPos**](/windows/desktop/api/Winuser/nf-winuser-getscrollpos), and [**GetScrollRange**](/windows/desktop/api/Winuser/nf-winuser-getscrollrange) functions support 32-bit scroll bar position data, there is a way to circumvent the 16-bit barrier of the **WM\_HSCROLL** and [**WM\_VSCROLL**](wm-vscroll.md) messages. See **GetScrollInfo** for a description of the technique. Read more on docs.microsoft.com. The WM\_VSCROLL message is sent to a window when a scroll event occurs in the window's standard vertical scroll bar. If an application processes this message, it should return zero. The SB\_THUMBTRACK request code is typically used by applications that provide feedback as the user drags the scroll box. If an application scrolls the content of the window, it must also reset the position of the scroll box by using the [**SetScrollPos**](/windows/desktop/api/Winuser/nf-winuser-setscrollpos) function. Note that the **WM\_VSCROLL** message carries only 16 bits of scroll box position data. Thus, applications that rely solely on **WM\_VSCROLL** (and [**WM\_HSCROLL**](wm-hscroll.md)) for scroll position data have a practical maximum position value of 65,535. However, because the [**SetScrollInfo**](/windows/desktop/api/Winuser/nf-winuser-setscrollinfo), [**SetScrollPos**](/windows/desktop/api/Winuser/nf-winuser-setscrollpos), [**SetScrollRange**](/windows/desktop/api/Winuser/nf-winuser-setscrollrange), [**GetScrollInfo**](/windows/desktop/api/Winuser/nf-winuser-getscrollinfo), [**GetScrollPos**](/windows/desktop/api/Winuser/nf-winuser-getscrollpos), and [**GetScrollRange**](/windows/desktop/api/Winuser/nf-winuser-getscrollrange) functions support 32-bit scroll bar position data, there is a way to circumvent the 16-bit barrier of the [**WM\_HSCROLL**](wm-hscroll.md) and **WM\_VSCROLL** messages. See **GetScrollInfo** for a description of the technique. Read more on docs.microsoft.com. Sent when a menu is about to become active. If an application processes this message, it should return zero. A **WM\_INITMENU** message is sent only when a menu is first accessed; only one **WM\_INITMENU** message is generated for each access. For example, moving the mouse across several menu items while holding down the button does not generate new messages. **WM\_INITMENU** does not provide information about menu items. WM_INITMENUPOPUP message - Sent when a drop-down menu or submenu is about to become active. This allows an application to modify the menu before it is displayed, without changing the entire menu. If an application processes this message, it should return zero. Learn more about this API from docs.microsoft.com. Passes information about a gesture. If an application processes this message, it should return 0. If the application does not process the message, it must call [DefWindowProc](/windows/win32/api/winuser/nf-winuser-defwindowproca). Not doing so will cause the application to leak memory because the touch input handle will not be closed and associated process memory will not be freed. The following table lists the supported gesture commands. | Gesture ID | Value (*dwID*) | Description | |-----------------------|----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **GID\_BEGIN** | 1 | Indicates a generic gesture is beginning. | | **GID\_END** | 2 | Indicates a generic gesture end. | | **GID\_ZOOM** | 3 | Indicates zoom start, zoom move, or zoom stop. The first **GID\_ZOOM** command message begins a zoom but does not cause any zooming. The second **GID\_ZOOM** command triggers a zoom relative to the state contained in the first **GID\_ZOOM**. | | **GID\_PAN** | 4 | Indicates pan move or pan start. The first **GID\_PAN** command indicates a pan start but does not perform any panning. With the second **GID\_PAN** command message, the application will begin panning. | | **GID\_ROTATE** | 5 | Indicates rotate move or rotate start. The first **GID\_ROTATE** command message indicates a rotate move or rotate start but will not rotate. The second **GID\_ROTATE** command message will trigger a rotation operation relative to state contained in the first **GID\_ROTATE**. | | **GID\_TWOFINGERTAP** | 6 | Indicates two-finger tap gesture. | | **GID\_PRESSANDTAP** | 7 | Indicates the press and tap gesture. | > [!Note] > In order to enable legacy support, messages with the **GID\_BEGIN** and **GID\_END** gesture commands need to be forwarded using [DefWindowProc](/windows/win32/api/winuser/nf-winuser-defwindowproca). The following table indicates the gesture arguments passed in the *lParam* and *wParam* parameters. | Gesture ID | Gesture | *ullArgument* | *ptsLocation* in [**GestureInfo**](/windows/desktop/api/winuser/nf-winuser-getgestureinfo) structure | |-----------------------|----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------| | **GID\_ZOOM** | Zoom In/Out | Indicates the distance between the two points. | Indicates the center of the zoom. | | **GID\_PAN** | Pan | Indicates the distance between the two points. | Indicates the current position of the pan. | | **GID\_ROTATE** | Rotate (pivot) | Indicates the angle of rotation if the **GF\_BEGIN** flag is set. Otherwise, this is the angle change since the rotation has started. This is signed to indicate the direction of the rotation. Use the [**GID\_ROTATE\_ANGLE\_FROM\_ARGUMENT**](/windows/desktop/api/winuser/nf-winuser-gid_rotate_angle_from_argument) and [**GID\_ROTATE\_ANGLE\_TO\_ARGUMENT**](/windows/desktop/api/winuser/nf-winuser-gid_rotate_angle_to_argument) macros to get and set the angle value. | This indicates the center of the rotation which is the stationary point that the target object is rotated around. | | **GID\_TWOFINGERTAP** | Two-finger Tap | Indicates the distance between the two fingers. | Indicates the center of the two fingers. | | **GID\_PRESSANDTAP** | Press and Tap | Indicates the delta between the first finger and the second finger. This value is stored in the lower 32 bits of the *ullArgument* in a **POINT** structure. | Indicates the position that the first finger comes down on. | > [!Note] > All distances and positions are provided in physical screen coordinates. > [!Note] > The *dwID* and *ullArgument* parameters should only be considered to be accompanying the GID\_\* commands and should not be altered by applications. Read more on docs.microsoft.com. Gives you a chance to set the gesture configuration. A value should be returned from [DefWindowProc](/windows/win32/api/winuser/nf-winuser-defwindowproca). When the **WM\_GESTURENOTIFY** message is received, the application can use [**SetGestureConfig**](/windows/desktop/api/winuser/nf-winuser-setgestureconfig) to specify the gestures to receive. This message should always be bubbled up using the [DefWindowProc](/windows/win32/api/winuser/nf-winuser-defwindowproca) function. > [!Note] > Handling the **WM\_GESTURENOTIFY** message will change the gesture configuration for the lifetime of the Window, not just for the next gesture. Read more on docs.microsoft.com. Sent to a menu's owner window when the user selects a menu item. If an application processes this message, it should return zero. If the high-order word of *wParam* contains 0xFFFF and the *lParam* parameter contains **NULL**, the system has closed the menu. Do not use the value 1 for the high-order word of *wParam*, because this value is specified as (**UINT**) [**HIWORD**](/previous-versions/windows/desktop/legacy/ms632657(v=vs.85))(*wParam*). If the value is 0xFFFF, it would be interpreted as 0x0000FFFF, not 1, because of the cast to a **UINT**. Read more on docs.microsoft.com. Sent when a menu is active and the user presses a key that does not correspond to any mnemonic or accelerator key. This message is sent to the window that owns the menu. An application that processes this message should return one of the following values in the high-order word of the return value. | Return code/value | Description | |----------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |
**MNC\_CLOSE**
1
| Informs the system that it should close the active menu.
| |
**MNC\_EXECUTE**
2
| Informs the system that it should choose the item specified in the low-order word of the return value. The owner window receives a [**WM\_COMMAND**](wm-command.md) message.
| |
**MNC\_IGNORE**
0
| Informs the system that it should discard the character the user pressed and create a short beep on the system speaker.
| |
**MNC\_SELECT**
3
| Informs the system that it should select the item specified in the low-order word of the return value.
| The low-order word is ignored if the high-order word contains 0 or 1. An application should process this message when an accelerator is used to select a menu item that displays a bitmap. Read more on docs.microsoft.com. Sent to the owner window of a modal dialog box or menu that is entering an idle state. A modal dialog box or menu enters an idle state when no messages are waiting in its queue after it has processed one or more previous messages. An application should return zero if it processes this message. You can suppress the **WM\_ENTERIDLE** message for a dialog box by creating the dialog box with the **DS\_NOIDLEMSG** style. Sent when the user releases the right mouse button while the cursor is on a menu item. The **WM\_MENURBUTTONUP** message allows applications to provide a context-sensitive menu also known as a shortcut menu for the menu item specified in this message. To display a context-sensitive menu for a menu item, call the [**TrackPopupMenuEx**](/windows/desktop/api/Winuser/nf-winuser-trackpopupmenuex) function with **TPM\_RECURSE**. Sent to the owner of a drag-and-drop menu when the user drags a menu item. The application should return one of the following values. | Return code/value | Description | |-----------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------| |
**MND\_CONTINUE**
0
| Menu should remain active. If the mouse is released, it should be ignored.
| |
**MND\_ENDMENU**
1
| Menu should be ended.
| The application can call the [**DoDragDrop**](/windows/win32/api/ole2/nf-ole2-dodragdrop) function in response to this message. To create a drag-and-drop menu, call [**SetMenuInfo**](/windows/desktop/api/Winuser/nf-winuser-setmenuinfo) with **MNS\_DRAGDROP**. Read more on docs.microsoft.com. Sent to the owner of a drag-and-drop menu when the mouse cursor enters a menu item or moves from the center of the item to the top or bottom of the item. The application should return one of the following values. | Return code/value | Description | |------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------| |
**MNGO\_NOERROR**
0x00000001
| An interface pointer was returned in the **pvObj** member of [**MENUGETOBJECTINFO**](/windows/win32/api/winuser/ns-winuser-menugetobjectinfo)
| |
**MNGO\_NOINTERFACE**
0x00000000
| The interface is not supported.
| Learn more about this API from docs.microsoft.com. Sent when a drop-down menu or submenu has been destroyed. If an application receives a [**WM\_INITMENUPOPUP**](wm-initmenupopup.md) message, it will receive a **WM\_UNINITMENUPOPUP** message. Sent when the user makes a selection from a menu. The **WM\_MENUCOMMAND** message gives you a handle to the menu so you can access the menu data in the [**MENUINFO**](/windows/win32/api/winuser/ns-winuser-menuinfo) structure and also gives you the index of the selected item, which is typically what applications need. In contrast, the [**WM\_COMMAND**](wm-command.md) message gives you the menu item identifier. The **WM\_MENUCOMMAND** message is sent only for menus that are defined with the **MNS\_NOTIFYBYPOS** flag set in the **dwStyle** member of the [**MENUINFO**](/windows/win32/api/winuser/ns-winuser-menuinfo) structure. Read more on docs.microsoft.com. An application sends the WM\_CHANGEUISTATE message to indicate that the UI state should be changed. A window should send this message to itself or its parent when it must change the UI state elements of all windows in the same hierarchy. The window procedure must let [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) process this message so that the entire window tree has a consistent UI state. When the top-level window receives the **WM\_CHANGEUISTATE** message, it sends a [**WM\_UPDATEUISTATE**](wm-updateuistate.md) message with the same parameters to all child windows. When the system processes the **WM\_UPDATEUISTATE** message, it makes the change in the UI state. If the low-order word of *wParam* is UIS\_INITIALIZE, the system will send the [**WM\_UPDATEUISTATE**](wm-updateuistate.md) message with a UI state based on the last input event. For example, if the last input came from the mouse, the system will hide the keyboard cues. And, if the last input came from the keyboard, the system will show the keyboard cues. If the state that results from processing **WM\_CHANGEUISTATE** is the same as the old state, [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) does not send this message. Read more on docs.microsoft.com. An application sends the WM\_UPDATEUISTATE message to change the UI state for the specified window and all its child windows. A window should send this message to change the UI state of all its child windows. In contrast to the [**WM\_CHANGEUISTATE**](wm-changeuistate.md) message, which is a notification, when [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) processes the **WM\_UPDATEUISTATE** message it changes the UI state and propagates the changes to all child windows. The [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function updates the UI state according to the *wParam* value. If the UI state is modified, the function sends the message to all the immediate child windows. **DefWindowProc** also sends this message when it receives a [**WM\_CHANGEUISTATE**](wm-changeuistate.md) message notifying the system that a child window intends to modify the UI state. Read more on docs.microsoft.com. An application sends the WM\_QUERYUISTATE message to retrieve the UI state for a window. The return value is **NULL** if the focus indicators and the keyboard accelerators are visible. Otherwise, the return value can be one or more of the following values. | Return code/value | Description | |---------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------| |
**UISF\_ACTIVE**
0x4
| A control should be drawn in the style used for active controls.
| |
**UISF\_HIDEACCEL**
0x2
| Keyboard accelerators are hidden.
| |
**UISF\_HIDEFOCUS**
0x1
| Focus indicators are hidden.
| Learn more about this API from docs.microsoft.com. An edit control that is not read-only or disabled sends the WM\_CTLCOLOREDIT message to its parent window when the control is about to be drawn. If an application processes this message, it must return the handle of a brush. The system uses the brush to paint the background of the edit control. If the application returns a brush that it created (for example, by using the [**CreateSolidBrush**](/windows/desktop/api/wingdi/nf-wingdi-createsolidbrush) or [**CreateBrushIndirect**](/windows/desktop/api/wingdi/nf-wingdi-createbrushindirect) function), the application must free the brush. If the application returns a system brush (for example, one that was retrieved by the [**GetStockObject**](/windows/desktop/api/wingdi/nf-wingdi-getstockobject) or [**GetSysColorBrush**](/windows/desktop/api/winuser/nf-winuser-getsyscolorbrush) function), the application does not need to free the brush. By default, the [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function selects the default system colors for the edit control. Read-only or disabled edit controls do not send the **WM\_CTLCOLOREDIT** message; instead, they send the [**WM\_CTLCOLORSTATIC**](wm-ctlcolorstatic.md) message. The **WM\_CTLCOLOREDIT** message is never sent between threads, it is only sent within the same thread. If a dialog box procedure handles this message, it should cast the desired return value to a **INT\_PTR** and return the value directly. If the dialog box procedure returns **FALSE**, then default message handling is performed. The DWL\_MSGRESULT value set by the [**SetWindowLong**](/windows/desktop/api/winuser/nf-winuser-setwindowlonga) function is ignored. **Rich Edit:** This message is not supported. To set the background color for a rich edit control, use the [**EM\_SETBKGNDCOLOR**](em-setbkgndcolor.md) message. Read more on docs.microsoft.com. Sent to the parent window of a list box before the system draws the list box. By responding to this message, the parent window can set the text and background colors of the list box by using the specified display device context handle. If an application processes this message, it must return a handle to a brush. The system uses the brush to paint the background of the list box. By default, the [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function selects the default system colors for the list box. The **WM\_CTLCOLORLISTBOX** message is never sent between threads. It is sent only within one thread. If a dialog box procedure handles this message, it should cast the desired return value to a **INT\_PTR** and return the value directly. If the dialog box procedure returns **FALSE**, then default message handling is performed. The **DWL\_MSGRESULT** value set by the [**SetWindowLong**](/windows/desktop/api/winuser/nf-winuser-setwindowlonga) function is ignored. Read more on docs.microsoft.com. The WM\_CTLCOLORBTN message is sent to the parent window of a button before drawing the button. The parent window can change the button's text and background colors. However, only owner-drawn buttons respond to the parent window processing this message. If an application processes this message, it must return a handle to a brush. The system uses the brush to paint the background of the button. If the application returns a brush that it created (for example, by using the [**CreateSolidBrush**](/windows/desktop/api/wingdi/nf-wingdi-createsolidbrush) or [**CreateBrushIndirect**](/windows/desktop/api/wingdi/nf-wingdi-createbrushindirect) function), the application must free the brush. If the application returns a system brush (for example, one that was retrieved by the [**GetStockObject**](/windows/desktop/api/wingdi/nf-wingdi-getstockobject) or [**GetSysColorBrush**](/windows/desktop/api/winuser/nf-winuser-getsyscolorbrush) function), the application does not need to free the brush. By default, the [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function selects the default system colors for the button. Buttons with the [**BS\_PUSHBUTTON**](button-styles.md), [**BS\_DEFPUSHBUTTON**](button-styles.md), or [**BS\_PUSHLIKE**](button-styles.md) styles do not use the returned brush. Buttons with these styles are always drawn with the default system colors. Drawing push buttons requires several different brushes-face, highlight, and shadow-but the **WM\_CTLCOLORBTN** message allows only one brush to be returned. To provide a custom appearance for push buttons, use an owner-drawn button. For more information, see [Creating Owner-Drawn Controls](user-controls-intro.md). The **WM\_CTLCOLORBTN** message is never sent between threads. It is sent only within one thread. The text color of a check box or radio button applies to the box or button, its check mark, and the text. The focus rectangle for these buttons remains the system default color (typically black). The text color of a group box applies to the text but not to the line that defines the box. The text color of a push button applies only to its focus rectangle; it does not affect the color of the text. If a dialog box procedure handles this message, it should cast the desired return value to a **INT\_PTR** and return the value directly. If the dialog box procedure returns **FALSE**, then default message handling is performed. The DWL\_MSGRESULT value set by the [**SetWindowLong**](/windows/desktop/api/winuser/nf-winuser-setwindowlonga) function is ignored. Read more on docs.microsoft.com. Sent to a dialog box before the system draws the dialog box. By responding to this message, the dialog box can set its text and background colors using the specified display device context handle. If an application processes this message, it must return a handle to a brush. The system uses the brush to paint the background of the dialog box. By default, the [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function selects the default system colors for the dialog box. The system does not automatically destroy the returned brush. It is the application's responsibility to destroy the brush when it is no longer needed. The **WM\_CTLCOLORDLG** message is never sent between threads. It is sent only within one thread. Note that the **WM\_CTLCOLORDLG** message is sent to the dialog box itself; all of the other **WM\_CTLCOLOR\*** messages are sent to the owner of the control. If a dialog box procedure handles this message, it should cast the desired return value to an **INT\_PTR** and return the value directly. If the dialog box procedure returns **FALSE**, then default message handling is performed. The **DWL\_MSGRESULT** value set by the [**SetWindowLong**](/windows/desktop/api/winuser/nf-winuser-setwindowlonga) function is ignored. Read more on docs.microsoft.com. The WM\_CTLCOLORSCROLLBAR message is sent to the parent window of a scroll bar control when the control is about to be drawn. If an application processes this message, it must return the handle to a brush. The system uses the brush to paint the background of the scroll bar control. If the application returns a brush that it created (for example, by using the [**CreateSolidBrush**](/windows/desktop/api/wingdi/nf-wingdi-createsolidbrush) or [**CreateBrushIndirect**](/windows/desktop/api/wingdi/nf-wingdi-createbrushindirect) function), the application must free the brush. If the application returns a system brush (for example, one that was retrieved by the [**GetStockObject**](/windows/desktop/api/wingdi/nf-wingdi-getstockobject) or [**GetSysColorBrush**](/windows/desktop/api/winuser/nf-winuser-getsyscolorbrush) function), the application does not need to free the brush. By default, the [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function selects the default system colors for the scroll bar control. The **WM\_CTLCOLORSCROLLBAR** message is never sent between threads; it is only sent within the same thread. If a dialog box procedure handles this message, it should cast the desired return value to a **INT\_PTR** and return the value directly. If the dialog box procedure returns **FALSE**, then default message handling is performed. The DWL\_MSGRESULT value set by the [**SetWindowLong**](/windows/desktop/api/winuser/nf-winuser-setwindowlonga) function is ignored. The **WM\_CTLCOLORSCROLLBAR** message is used only by child scroll bar controls. Scrollbars attached to a window (WS\_SCROLL and WS\_VSCROLL) do not generate this message. To customize the appearance of scrollbars attached to a window, use the flat scroll bar functions. Read more on docs.microsoft.com. A static control, or an edit control that is read-only or disabled, sends the WM\_CTLCOLORSTATIC message to its parent window when the control is about to be drawn. If an application processes this message, the return value is a handle to a brush that the system uses to paint the background of the static control. If the application returns a brush that it created (for example, by using the [**CreateSolidBrush**](/windows/desktop/api/wingdi/nf-wingdi-createsolidbrush) or [**CreateBrushIndirect**](/windows/desktop/api/wingdi/nf-wingdi-createbrushindirect) function), the application must free the brush. If the application returns a system brush (for example, one that was retrieved by the [**GetStockObject**](/windows/desktop/api/wingdi/nf-wingdi-getstockobject) or [**GetSysColorBrush**](/windows/desktop/api/winuser/nf-winuser-getsyscolorbrush) function), the application does not need to free the brush. By default, the [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function selects the default system colors for the static control. You can set the text background color of a disabled edit control, but you cannot set the text foreground color. The system always uses COLOR\_GRAYTEXT. Edit controls that are not read-only or disabled do not send the **WM\_CTLCOLORSTATIC** message; instead, they send the [**WM\_CTLCOLOREDIT**](wm-ctlcoloredit.md) message. The **WM\_CTLCOLORSTATIC** message is never sent between threads; it is sent only within the same thread. If a dialog box procedure handles this message, it should cast the desired return value to a **INT\_PTR** and return the value directly. If the dialog box procedure returns **FALSE**, then default message handling is performed. The DWL\_MSGRESULT value set by the [**SetWindowLong**](/windows/desktop/api/winuser/nf-winuser-setwindowlonga) function is ignored. Read more on docs.microsoft.com. Posted to a window when the cursor moves. If the mouse is not captured, the message is posted to the window that contains the cursor. Otherwise, the message is posted to the window that has captured the mouse. If an application processes this message, it should return zero. Use the following code to obtain the horizontal and vertical position: This doc was truncated. Read more on docs.microsoft.com. Posted when the user releases the left mouse button while the cursor is in the client area of a window. If an application processes this message, it should return zero. Use the following code to obtain the horizontal and vertical position: This doc was truncated. Read more on docs.microsoft.com. Posted when the user double-clicks the left mouse button while the cursor is in the client area of a window. If an application processes this message, it should return zero. Use the following code to obtain the horizontal and vertical position: This doc was truncated. Read more on docs.microsoft.com. Posted when the user presses the right mouse button while the cursor is in the client area of a window. If an application processes this message, it should return zero. Use the following code to obtain the horizontal and vertical position: This doc was truncated. Read more on docs.microsoft.com. Posted when the user releases the right mouse button while the cursor is in the client area of a window. If an application processes this message, it should return zero. Use the following code to obtain the horizontal and vertical position: This doc was truncated. Read more on docs.microsoft.com. Posted when the user double-clicks the right mouse button while the cursor is in the client area of a window. If an application processes this message, it should return zero. Only windows that have the **CS\_DBLCLKS** style can receive **WM\_RBUTTONDBLCLK** messages, which the system generates whenever the user presses, releases, and again presses the right mouse button within the system's double-click time limit. Double-clicking the right mouse button actually generates four messages: [**WM\_RBUTTONDOWN**](wm-rbuttondown.md), [**WM\_RBUTTONUP**](wm-rbuttonup.md), **WM\_RBUTTONDBLCLK**, and **WM\_RBUTTONUP** again. Use the following code to obtain the horizontal and vertical position: This doc was truncated. Read more on docs.microsoft.com. Posted when the user presses the middle mouse button while the cursor is in the client area of a window. If an application processes this message, it should return zero. Use the following code to obtain the horizontal and vertical position: This doc was truncated. Read more on docs.microsoft.com. Posted when the user releases the middle mouse button while the cursor is in the client area of a window. If an application processes this message, it should return zero. Use the following code to obtain the horizontal and vertical position: This doc was truncated. Read more on docs.microsoft.com. Posted when the user double-clicks the middle mouse button while the cursor is in the client area of a window. If an application processes this message, it should return zero. Use the following code to obtain the horizontal and vertical position: This doc was truncated. Read more on docs.microsoft.com. Sent to the focus window when the mouse wheel is rotated. If an application processes this message, it should return zero. Use the following code to get the information in the *wParam* parameter: This doc was truncated. Read more on docs.microsoft.com. Posted when the user presses the first or second X button while the cursor is in the client area of a window. If an application processes this message, it should return **TRUE**. For more information about processing the return value, see the Remarks section. Use the following code to get the information in the *wParam* parameter: This doc was truncated. Read more on docs.microsoft.com. Posted when the user releases the first or second X button while the cursor is in the client area of a window. If an application processes this message, it should return **TRUE**. For more information about processing the return value, see the Remarks section. Use the following code to get the information in the *wParam* parameter: This doc was truncated. Read more on docs.microsoft.com. Posted when the user double-clicks the first or second X button while the cursor is in the client area of a window. If an application processes this message, it should return **TRUE**. For more information about processing the return value, see the Remarks section. Use the following code to get the information in the *wParam* parameter: This doc was truncated. Read more on docs.microsoft.com. Sent to the active window when the mouse's horizontal scroll wheel is tilted or rotated. If an application processes this message, it should return zero. Use the following code to obtain the information in the *wParam* parameter. This doc was truncated. Read more on docs.microsoft.com. Sent to a window when a significant action occurs on a descendant window. If the application processes this message, it returns zero. If the application does not process this message, it calls [**DefWindowProc**](/windows/win32/api/winuser/nf-winuser-defwindowproca). This message is also sent to all ancestor windows of the child window, including the top-level window. All child windows, except those that have the **WS_EX_NOPARENTNOTIFY** extended window style, send this message to their parent windows. By default, child windows in a dialog box have the **WS_EX_NOPARENTNOTIFY** style, unless the [**CreateWindowEx**](/windows/win32/api/winuser/nf-winuser-createwindowexa) function is called to create the child window without this style. This notification provides the child window's ancestor windows an opportunity to examine the pointer information and, if required, capture the pointer using the pointer capture functions. Read more on docs.microsoft.com. Notifies an application's main window procedure that a menu modal loop has been entered. An application should return zero if it processes this message. The [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function returns zero. Notifies an application's main window procedure that a menu modal loop has been exited. An application should return zero if it processes this message. The [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function returns zero. Sent to an application when the right or left arrow key is used to switch between the menu bar and the system menu. In responding to this message, the application can specify the menu to switch to in the **hmenuNext** member of [**MDINEXTMENU**](/windows/win32/api/winuser/ns-winuser-mdinextmenu) and the window to receive the menu notification messages in the **hwndNext** member of the **MDINEXTMENU** structure. You must set both members for the changes to take effect (they are initially **NULL**). Sent to a window that the user is resizing. By processing this message, an application can monitor the size and position of the drag rectangle and, if needed, change its size or position. Type: **LRESULT** An application should return **TRUE** if it processes this message. Learn more about this API from docs.microsoft.com. Sent to the window that is losing the mouse capture. An application should return zero if it processes this message. A window receives this message even if it calls [**ReleaseCapture**](/windows/win32/api/winuser/nf-winuser-releasecapture) itself. An application should not attempt to set the mouse capture in response to this message. When it receives this message, a window should redraw itself, if necessary, to reflect the new mouse-capture state. Read more on docs.microsoft.com. Sent to a window that the user is moving. By processing this message, an application can monitor the position of the drag rectangle and, if needed, change its position. Type: **LRESULT** An application should return **TRUE** if it processes this message. Learn more about this API from docs.microsoft.com. Notifies applications that a power-management event has occurred. An application should return **TRUE** if it processes this message. The system always sends a [PBT\_APMRESUMEAUTOMATIC](pbt-apmresumeautomatic.md) message whenever the system resumes. If the system resumes in response to user input such as pressing a key, the system also sends a **PBT\_APMRESUMESUSPEND** message after sending PBT\_APMRESUMEAUTOMATIC. **WM\_POWERBROADCAST** messages do not distinguish between different low-power states. An application can determine only that the system is entering or has resumed from a low-power state; it cannot determine the specific power state. The system records details about power state transitions in the Windows System event log. To prevent the system from transitioning to a low-power state in Windows Vista, an application must call [**SetThreadExecutionState**](/windows/desktop/api/Winbase/nf-winbase-setthreadexecutionstate) to inform the system that it is in use. The following messages are not supported on any of the operating systems specified in the Requirements section: - PBT_APMQUERYSTANDBY - PBT_APMQUERYSTANDBYFAILED - PBT_APMSTANDBY - PBT_APMRESUMESTANDBY Read more on docs.microsoft.com. An application sends the WM\_MDICREATE message to a multiple-document interface (MDI) client window to create an MDI child window. Type: **HWND** If the message succeeds, the return value is the handle to the new child window. If the message fails, the return value is **NULL**. The MDI child window is created with the [**window style**](window-styles.md) bits **WS\_CHILD**, **WS\_CLIPSIBLINGS**, **WS\_CLIPCHILDREN**, **WS\_SYSMENU**, **WS\_CAPTION**, **WS\_THICKFRAME**, **WS\_MINIMIZEBOX**, and **WS\_MAXIMIZEBOX**, plus additional style bits specified in the [**MDICREATESTRUCT**](/windows/win32/api/winuser/ns-winuser-mdicreatestructa) structure. The system adds the title of the new child window to the window menu of the frame window. An application should use this message to create all child windows of the client window. If an MDI client window receives any message that changes the activation of its child windows while the active child window is maximized, the system restores the active child window and maximizes the newly activated child window. When an MDI child window is created, the system sends the [**WM\_CREATE**](wm-create.md) message to the window. The *lParam* parameter of the **WM\_CREATE** message contains a pointer to a [**CREATESTRUCT**](/windows/win32/api/winuser/ns-winuser-createstructa) structure. The *lpCreateParams* member of this structure contains a pointer to the [**MDICREATESTRUCT**](/windows/win32/api/winuser/ns-winuser-mdicreatestructa) structure passed with the **WM\_MDICREATE** message that created the MDI child window. An application should not send a second **WM\_MDICREATE** message while a **WM\_MDICREATE** message is still being processed. For example, it should not send a **WM\_MDICREATE** message while an MDI child window is processing its **WM\_MDICREATE** message. Read more on docs.microsoft.com. An application sends the WM\_MDIDESTROY message to a multiple-document interface (MDI) client window to close an MDI child window. Type: **zero** This message always returns zero. This message removes the title of the MDI child window from the MDI frame window and deactivates the child window. An application should use this message to close all MDI child windows. If an MDI client window receives a message that changes the activation of its child windows and the active MDI child window is maximized, the system restores the active child window and maximizes the newly activated child window. Read more on docs.microsoft.com. An application sends the WM\_MDIACTIVATE message to a multiple-document interface (MDI) client window to instruct the client window to activate a different MDI child window. Type: **LRESULT** If an application sends this message to an MDI client window, the return value is zero. An MDI child window should return zero if it processes this message. As the client window processes this message, it sends **WM\_MDIACTIVATE** to the child window being deactivated and to the child window being activated. The message parameters received by an MDI child window are as follows:
*wParam*
A handle to the MDI child window being deactivated.
*lParam*
A handle to the MDI child window being activated.
An MDI child window is activated independently of the MDI frame window. When the frame window becomes active, the child window last activated by using the **WM\_MDIACTIVATE** message receives the [**WM\_NCACTIVATE**](wm-ncactivate.md) message to draw an active window frame and title bar; the child window does not receive another **WM\_MDIACTIVATE** message. Read more on docs.microsoft.com. An application sends the WM\_MDIRESTORE message to a multiple-document interface (MDI) client window to restore an MDI child window from maximized or minimized size. Type: **zero** The return value is always zero. Learn more about this API from docs.microsoft.com. An application sends the WM\_MDINEXT message to a multiple-document interface (MDI) client window to activate the next or previous child window. Type: **zero** The return value is always zero. If an MDI client window receives any message that changes the activation of its child windows while the active MDI child window is maximized, the system restores the active child window and maximizes the newly activated child window. An application sends the WM\_MDIMAXIMIZE message to a multiple-document interface (MDI) client window to maximize an MDI child window. Type: **zero** The return value is always zero. If an MDI client window receives any message that changes the activation of its child windows while the currently active MDI child window is maximized, the system restores the active child window and maximizes the newly activated child window. An application sends the WM\_MDITILE message to a multiple-document interface (MDI) client window to arrange all of its MDI child windows in a tile format. Type: **BOOL** If the message succeeds, the return value is **TRUE**. If the message fails, the return value is **FALSE**. Learn more about this API from docs.microsoft.com. An application sends the WM\_MDICASCADE message to a multiple-document interface (MDI) client window to arrange all its child windows in a cascade format. Type: **BOOL** If the message succeeds, the return value is **TRUE**. If the message fails, the return value is **FALSE**. Learn more about this API from docs.microsoft.com. An application sends the WM\_MDIICONARRANGE message to a multiple-document interface (MDI) client window to arrange all minimized MDI child windows. It does not affect child windows that are not minimized. Learn more about this API from docs.microsoft.com. An application sends the WM\_MDIGETACTIVE message to a multiple-document interface (MDI) client window to retrieve the handle to the active MDI child window. Type: **HWND** The return value is the handle to the active MDI child window. Learn more about this API from docs.microsoft.com. An application sends the WM\_MDISETMENU message to a multiple-document interface (MDI) client window to replace the entire menu of an MDI frame window, to replace the window menu of the frame window, or both. Type: **HMENU** If the message succeeds, the return value is the handle to the old frame window menu. If the message fails, the return value is zero. After sending this message, an application must call the [**DrawMenuBar**](/windows/win32/api/winuser/nf-winuser-drawmenubar) function to update the menu bar. If this message replaces the window menu, the MDI child window menu items are removed from the previous window menu and added to the new window menu. If an MDI child window is maximized and this message replaces the MDI frame window menu, the window menu icon and restore icon are removed from the previous frame window menu and added to the new frame window menu. Read more on docs.microsoft.com. Sent one time to a window after it enters the moving or sizing modal loop. Type: **LRESULT** An application should return zero if it processes this message. Learn more about this API from docs.microsoft.com. Sent one time to a window, after it has exited the moving or sizing modal loop. Type: **LRESULT** An application should return zero if it processes this message. Learn more about this API from docs.microsoft.com. Sent when the user drops a file on the window of an application that has registered itself as a recipient of dropped files. An application should return zero if it processes this message. The HDROP handle is declared in Shellapi.h. You must include this header in your build to use **WM\_DROPFILES**. For further discussion of how to use drag-and-drop to transfer Shell data, see [Transferring Shell Data Using Drag-and-Drop or the Clipboard](dragdrop.md). An application sends the WM\_MDIREFRESHMENU message to a multiple-document interface (MDI) client window to refresh the window menu of the MDI frame window. Type: **HMENU** If the message succeeds, the return value is the handle to the frame window menu. If the message fails, the return value is **NULL**. After sending this message, an application must call the [**DrawMenuBar**](/windows/win32/api/winuser/nf-winuser-drawmenubar) function to update the menu bar. Sent to a window when there is a change in the settings of a monitor that has a digitizer attached to it. This message contains information regarding the scaling of the display mode. If the application processes this message, it should return zero. If the application does not process this message, it should call [**DefWindowProc**](/windows/win32/api/winuser/nf-winuser-defwindowproca). Learn more about this API from docs.microsoft.com. Sent to a window when a pointer device is detected within range of an input digitizer. This message contains information regarding the device and its proximity. If the application processes this message, it should return zero. If the application does not process this message, it should call [**DefWindowProc**](/windows/win32/api/winuser/nf-winuser-defwindowproca). Learn more about this API from docs.microsoft.com. Sent to a window when a pointer device has departed the range of an input digitizer. This message contains information regarding the device and its proximity. If the application processes this message, it should return zero. If the application does not process this message, it should call [**DefWindowProc**](/windows/win32/api/winuser/nf-winuser-defwindowproca). Learn more about this API from docs.microsoft.com. Notifies the window when one or more touch points, such as a finger or pen, touches a touch-sensitive digitizer surface. If an application processes this message, it should return zero. If the application does not process the message, it must call [DefWindowProc](/windows/win32/api/winuser/nf-winuser-defwindowproca). Not doing so causes the application to leak memory because the touch input handle is not closed and associated process memory is not freed. **WM\_TOUCH** messages do not respect **HTTRANSPARENT** regions of windows. If a window returns **HTTRANSPARENT** in response to a **WM\_NCHITTEST** message, mouse messages go to the parent, and **WM\_TOUCH** messages go directly to the window. Posted to provide an update on a pointer that made contact over the non-client area of a window or when a hovering uncaptured contact moves over the non-client area of a window. If an application processes this message, it should return zero. If the application does not process this message, it should call [**DefWindowProc**](/windows/win32/api/winuser/nf-winuser-defwindowproca). If the application does not process this message, [**DefWindowProc**](/windows/win32/api/winuser/nf-winuser-defwindowproca) may perform one or more system actions depending on the hit-test result included in the message. Typically, applications should not need to handle this message. Posted when a pointer makes contact over the non-client area of a window. If an application processes this message, it should return zero. If the application does not process this message, it should call [**DefWindowProc**](/windows/win32/api/winuser/nf-winuser-defwindowproca). If the application does not process this message, [**DefWindowProc**](/windows/win32/api/winuser/nf-winuser-defwindowproca) may perform one or more system actions depending on the hit-test result included in the message. Typically, applications should not need to handle this message. Posted when a pointer that made contact over the non-client area of a window breaks contact. If an application processes this message, it should return zero. If the application does not process this message, it should call [**DefWindowProc**](/windows/win32/api/winuser/nf-winuser-defwindowproca). If the application does not process this message, [**DefWindowProc**](/windows/win32/api/winuser/nf-winuser-defwindowproca) may perform one or more system actions depending on the hit-test result included in the message. Typically, applications should not need to handle this message. Posted to provide an update on a pointer that made contact over the client area of a window or on a hovering uncaptured pointer over the client area of a window. If an application processes this message, it should return zero. If the application does not process this message, it should call [**DefWindowProc**](/windows/win32/api/winuser/nf-winuser-defwindowproca). Each pointer has a unique pointer identifier during its lifetime. The lifetime of a pointer begins when it is first detected. A [**WM_POINTERENTER**](wm-pointerenter.md) message is generated if a hovering pointer is detected. A [**WM_POINTERDOWN**](wm-pointerdown.md) message followed by a **WM_POINTERENTER** message is generated if a non-hovering pointer is detected. During its lifetime, a pointer may generate a series of **WM_POINTERUPDATE** messages while it is hovering or in contact. The lifetime of a pointer ends when it is no longer detected. This generates a [**WM_POINTERLEAVE**](wm-pointerleave.md) message. When a pointer is aborted, [**POINTER_FLAG_CANCELED**](pointer-flags-contants.md) is set. A [**WM_POINTERLEAVE**](wm-pointerleave.md) message may also be generated when a non-captured pointer moves outside the bounds of a window. To obtain the horizontal and vertical position of a pointer, use the following: This doc was truncated. Read more on docs.microsoft.com. Posted when a pointer makes contact over the client area of a window. If an application processes this message, it should return zero. If the application does not process this message, it should call [**DefWindowProc**](/windows/win32/api/winuser/nf-winuser-defwindowproca). > ![Important] > When a window loses capture of a pointer and it receives the [**WM_POINTERCAPTURECHANGED**](wm-pointercapturechanged.md) notification, it typically will not receive any further notifications. For this reason, it is important that you not make any assumptions based on evenly paired **WM_POINTERDOWN**/[**WM_POINTERUP**](wm-pointerup.md) or [**WM_POINTERENTER**](wm-pointerenter.md)/[**WM_POINTERLEAVE**](wm-pointerleave.md) notifications. Each pointer has a unique pointer identifier during its lifetime. The lifetime of a pointer begins when it is first detected. A [**WM_POINTERENTER**](wm-pointerenter.md) message is generated if a hovering pointer is detected. A **WM_POINTERDOWN** message followed by a **WM_POINTERENTER** message is generated if a non-hovering pointer is detected. During its lifetime, a pointer may generate a series of [**WM_POINTERUPDATE**](wm-pointerupdate.md) messages while it is hovering or in contact. The lifetime of a pointer ends when it is no longer detected. This generates a [**WM_POINTERLEAVE**](wm-pointerleave.md) message. When a pointer is aborted, [**POINTER_FLAG_CANCELED**](pointer-flags-contants.md) is set. A [**WM_POINTERLEAVE**](wm-pointerleave.md) message may also be generated when a non-captured pointer moves outside the bounds of a window. To obtain the horizontal and vertical position of a pointer, use the following: This doc was truncated. Read more on docs.microsoft.com. Posted when a pointer that made contact over the client area of a window breaks contact. If an application processes this message, it should return zero. If the application does not process this message, it should call [**DefWindowProc**](/windows/win32/api/winuser/nf-winuser-defwindowproca). > ![Important] > When a window loses capture of a pointer and it receives the [**WM_POINTERCAPTURECHANGED**](wm-pointercapturechanged.md) notification, it typically will not receive any further notifications. For this reason, it is important that you not make any assumptions based on evenly paired [**WM_POINTERDOWN**](wm-pointerdown.md)/**WM_POINTERUP** or [**WM_POINTERENTER**](wm-pointerenter.md)/[**WM_POINTERLEAVE**](wm-pointerleave.md) notifications. Each pointer has a unique pointer identifier during its lifetime. The lifetime of a pointer begins when it is first detected. A [**WM_POINTERENTER**](wm-pointerenter.md) message is generated if a hovering pointer is detected. A [**WM_POINTERDOWN**](wm-pointerdown.md) message followed by a **WM_POINTERENTER** message is generated if a non-hovering pointer is detected. During its lifetime, a pointer may generate a series of [**WM_POINTERUPDATE**](wm-pointerupdate.md) messages while it is hovering or in contact. The lifetime of a pointer ends when it is no longer detected. This generates a [**WM_POINTERLEAVE**](wm-pointerleave.md) message. When a pointer is aborted, [**POINTER_FLAG_CANCELED**](pointer-flags-contants.md) is set. A [**WM_POINTERLEAVE**](wm-pointerleave.md) message may also be generated when a non-captured pointer moves outside the bounds of a window. To obtain the horizontal and vertical position of a pointer, use the following: Use the following code to obtain the horizontal and vertical position: This doc was truncated. Read more on docs.microsoft.com. Sent to a window when a new pointer enters detection range over the window (hover) or when an existing pointer moves within the boundaries of the window. If an application processes this message, it should return zero. If the application does not process this message, it should call [**DefWindowProc**](/windows/win32/api/winuser/nf-winuser-defwindowproca). The **WM_POINTERENTER** notification can be used by a window to provide feedback to the user while the pointer is over its surface or to otherwise react to the presence of a pointer over its surface. This notification is only sent to the window that is receiving input for the pointer. The following table lists some of the situations in which this notification is sent. | Action | Flags Set | Notifications Sent To | |----------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------| | A new pointer enters detection range (hover). | [**IS_POINTER_NEW_WPARAM**](/windows/win32/api/winuser/nf-winuser-is_pointer_new_wparam)
[**IS_POINTER_INRANGE_WPARAM**](/windows/win32/api/winuser/nf-winuser-is_pointer_new_wparam)
| Window over which the pointer enters detection range. | | A hovering pointer crosses within the window boundaries. | [**IS_POINTER_INRANGE_WPARAM**](/windows/win32/api/winuser/nf-winuser-is_pointer_inrange_wparam)
| Window within which the pointer has crossed. | > ![Important] > When a window loses capture of a pointer and it receives the [**WM_POINTERCAPTURECHANGED**](wm-pointercapturechanged.md) notification, it typically will not receive any further notifications. For this reason, it is important that you not make any assumptions based on evenly paired [**WM_POINTERDOWN**](wm-pointerdown.md)/[**WM_POINTERUP**](wm-pointerup.md) or **WM_POINTERENTER**/[**WM_POINTERLEAVE**](wm-pointerleave.md) notifications. When inputs come from the mouse, as a result of mouse and pointer message integration, **WM_POINTERENTER** is not sent. Read more on docs.microsoft.com. Sent to a window when a pointer leaves detection range over the window (hover) or when a pointer moves outside the boundaries of the window. If an application processes this message, it should return zero. If the application does not process this message, it should call [**DefWindowProc**](/windows/win32/api/winuser/nf-winuser-defwindowproca). The **WM_POINTERLEAVE** notification can be used by a window to change mode or stop any feedback to the user while the pointer is over the window surface. This notification is only sent to the window that is receiving input for the pointer. The following table lists some of the situations in which this notification is sent. | Action | Flags Set | Notifications Sent To | |-----------------------------------------------|-------------------------------------------------------------------|------------------------------------------------------| | A hovering pointer crosses window boundaries. | [**IS_POINTER_INRANGE_WPARAM**](/windows/win32/api/winuser/nf-winuser-is_pointer_inrange_wparam) | Window outside of whose boundary the pointer moved. | | A pointer goes out of detection range. | N/A | Window for which the pointer leaves detection range. | > ![Important] > When a window loses capture of a pointer and it receives the [**WM_POINTERCAPTURECHANGED**](wm-pointercapturechanged.md) notification, it typically will not receive any further notifications. For this reason, it is important that you not make any assumptions based on evenly paired [**WM_POINTERDOWN**](wm-pointerdown.md)/[**WM_POINTERUP**](wm-pointerup.md) or [**WM_POINTERENTER**](wm-pointerenter.md)/**WM_POINTERLEAVE** notifications. If contact is maintained with the input digitizer and the pointer moves outside the window, **WM_POINTERLEAVE** is not generated. **WM_POINTERLEAVE** is generated only when a hovering pointer crosses window boundaries or contact is terminated. **WM_POINTERLEAVE** is posted to the posted message queue if the input is originated from a mouse device. Read more on docs.microsoft.com. Sent to an inactive window when a primary pointer generates a WM_POINTERDOWN over the window. If an application processes this message, it should return one of the values described in the Remarks section. If the application does not process this message, it should call [**DefWindowProc**](/windows/win32/api/winuser/nf-winuser-defwindowproca). An application can handle this message and return one of the following values to determine how the system processes the activation and the activating input: - PA_ACTIVATE - PA_NOACTIVATE It is important to note that, when the user is interacting with the system with multiple simultaneous pointers, the activation opportunity that the **WM_POINTERACTIVATE** message represents is available to applications only for the first of those pointers. Applications should, therefore, be aware that they may still receive input from pointers while they are inactive. If the application does not handle this message, [**DefWindowProc**](/windows/win32/api/winuser/nf-winuser-defwindowproca) passes the message to the parent window. Read more on docs.microsoft.com. Sent to a window that is losing capture of an input pointer. If an application processes this message, it should return zero. If the application does not process this message, it should call [**DefWindowProc**](/windows/win32/api/winuser/nf-winuser-defwindowproca). A window should use this notification to stop processing subsequent messages and initiate any cleanup required for the pointer being lost. Processing of gestures associated with the pointer should also be terminated (for example, by calling [**StopInteractionContext**](/windows/win32/api/interactioncontext/nf-interactioncontext-stopinteractioncontext)) and remaining contacts re-associated with the window. Typically, if a window receives the **WM_POINTERCAPTURECHANGED** notification, no subsequent notifications related to the input pointer are received. Because of this, do not depend on paired notifications such as [**WM_POINTERENTER**](wm-pointerenter.md) and [**WM_POINTERLEAVE**](wm-pointerleave.md). **WM_POINTERCAPTURECHANGED** does not include [**POINTER_INFO**](/windows/win32/api/winuser/ns-winuser-pointer_info) data. Other than the [**POINTER_FLAG_CAPTURECHANGED**](pointer-flags-contants.md) flag being set, the data returned by [**GetPointerInfo**](/windows/win32/api/winuser/ns-winuser-pointer_info) (or any variant) is identical to that returned prior to the notification. If the application does not process this notification, [**DefWindowProc**](/windows/win32/api/winuser/nf-winuser-defwindowproca) may generate one or more [**WM_GESTURE**](../wintouch/wm-gesture.md) messages or, if a gesture is not recognized, **DefWindowProc** may generate mouse input. If an application selectively consumes some pointer input and passes the rest to [**DefWindowProc**](/windows/win32/api/winuser/nf-winuser-defwindowproca), the resulting behavior is undefined. Read more on docs.microsoft.com. Sent to a window on a touch down in order to determine the most probable touch target. If one or more elements are within the touch contact area, an application should return the result of [**PackTouchHitTestingProximityEvaluation**](/windows/win32/api/winuser/nf-winuser-packtouchhittestingproximityevaluation). If no elements are within the touch contact area, an application should set the value of **score** in [**TOUCH_HIT_TESTING_PROXIMITY_EVALUATION**](/windows/win32/api/winuser/ns-winuser-touch_hit_testing_proximity_evaluation) to [**TOUCH_HIT_TESTING_PROXIMITY_FARTHEST**](/previous-versions/windows/desktop/input_touchhittest/hit-testing-scores) and call [**PackTouchHitTestingProximityEvaluation**](/windows/win32/api/winuser/nf-winuser-packtouchhittestingproximityevaluation) to get the LRESULT return value. If the application does not process this message, it must call [**DefWindowProc**](/windows/win32/api/winuser/nf-winuser-defwindowproca). This message is sent to windows that register through the [**RegisterTouchHitTestingWindow**](/windows/win32/api/winuser/nf-winuser-registertouchhittestingwindow) function. Posted to the window with foreground keyboard focus when a scroll wheel is rotated. If the application processes this message, it should return zero. If the application does not process this message, it should call [**DefWindowProc**](/windows/win32/api/winuser/nf-winuser-defwindowproca). To retrieve the wheel scroll units, use the **inputData** filed of the [**POINTER_INFO**](/windows/win32/api/winuser/ns-winuser-pointer_info) structure returned by calling [**GetPointerInfo**](/windows/win32/api/winuser/ns-winuser-pointer_info) function. This field contains a signed value and is expressed in a multiple of **WHEEL_DELTA**. A positive value indicates a rotation forward and a negative value indicates a rotation backward. Note that the wheel inputs may be delivered even if the mouse cursor is located outside of application s window. The wheel messages are delivered in a way very similar to the keyboard inputs. The focus window of the foregournd message queue receives the wheel messages. Read more on docs.microsoft.com. Posted to the window with foreground keyboard focus when a horizontal scroll wheel is rotated. If the application processes this message, it should return zero. If the application does not process this message, it should call [**DefWindowProc**](/windows/win32/api/winuser/nf-winuser-defwindowproca). To retrieve the wheel scroll units, use the **inputData** filed of the [**POINTER_INFO**](/windows/win32/api/winuser/ns-winuser-pointer_info) structure returned by calling [**GetPointerInfo**](/windows/win32/api/winuser/ns-winuser-pointer_info) function. This field contains a signed value and is expressed in a multiple of **WHEEL_DELTA**. A positive value indicates a rotation forward and a negative value indicates a rotation backward. Note that the wheel inputs may be delivered even if the mouse cursor is located outside of application s window. The wheel messages are delivered in a way very similar to the keyboard inputs. The focus window of the foregournd message queue receives the wheel messages. Read more on docs.microsoft.com. Sent when ongoing pointer input, for an existing pointer ID, transitions from one process to another across content configured for cross-process chaining (AddContentWithCrossProcessChaining). NULL This message is not sent when a [**WM_POINTERDOWN**](wm-pointerdown.md) message is posted for a new pointer ID on a different process. A [**WM_POINTERDOWN**](wm-pointerdown.md) message is not sent if a **WM_POINTERROUTEDTO** message is posted first. Read more on docs.microsoft.com. Occurs on the process receiving input when the pointer input is routed to another process.AddContentWithCrossProcessChaining). NULL This message is not sent with either a [**WM_POINTERUP**](wm-pointerup.md) message or a [**WM_POINTERCAPTURECHANGED**](wm-pointercapturechanged.md) message. Sent to all processes (configured for cross-process chaining through AddContentWithCrossProcessChaining and not currently handling pointer input) ever associated with a specific pointer ID, when a WM_POINTERUP message is received on the current process. NULL Learn more about this API from docs.microsoft.com. Sent to an application when a window is activated. A window receives this message through its WindowProc function. Returns the value returned by [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) or [**ImmIsUIMessage**](/windows/desktop/api/Imm/nf-imm-immisuimessagea). If the application has created an IME window, it should call [**ImmIsUIMessage**](/windows/desktop/api/Imm/nf-imm-immisuimessagea). Otherwise, it should pass this message to [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca). If the application draws the composition window, the default IME window does not have to show its composition window. In this case, the application must clear the **ISC\_SHOWUICOMPOSITIONWINDOW** value from the *lParam* parameter before passing the message to [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) or [**ImmIsUIMessage**](/windows/desktop/api/Imm/nf-imm-immisuimessagea). To display a certain user interface window, an application should remove the corresponding value so that the IME will not display it. Read more on docs.microsoft.com. Sent to an application to notify it of changes to the IME window. A window receives this message through its WindowProc function. The return value depends on the command sent. An application processes this message if it is responsible for managing the IME window. Sent by an application to direct the IME window to carry out the requested command. The message returns a command-specific value. Learn more about this API from docs.microsoft.com. Sent to an application when the IME window finds no space to extend the area for the composition window. A window receives this message through its WindowProc function. This message has no parameters. This message has no return value. The application should use the [IMC\_SETCOMPOSITIONWINDOW](imc-setcompositionwindow.md) command to specify how the window should be displayed. The IME window, instead of the IME, sends this notification message by the [**SendMessage**](/windows/win32/api/winuser/nf-winuser-sendmessage) function. Read more on docs.microsoft.com. Sent to an application when the operating system is about to change the current IME. A window receives this message through its WindowProc function. This message has no return value. An application that has created an IME window should pass this message to that window so that it can retrieve the keyboard layout handle to the newly selected IME. The [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function processes this message by passing the information to the default IME window. Read more on docs.microsoft.com. Sent to an application when the IME gets a character of the conversion result. A window receives this message through its WindowProc function. Unlike the [**WM\_CHAR**](../inputdev/wm-char.md) message for a non-Unicode window, this message can include double-byte and single-byte character values. For a Unicode window, this message is the same as WM\_CHAR. For a non-Unicode window, if the WM\_IME\_CHAR message includes a double-byte character and the application passes this message to [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca), the IME converts this message into two WM\_CHAR messages, each containing one byte of the double-byte character. Read more on docs.microsoft.com. Sent to an application to provide commands and request information. A window receives this message through its WindowProc function. Returns a command-specific value. Learn more about this API from docs.microsoft.com. Sent to an application by the IME to notify the application of a key press and to keep message order. A window receives this message through its WindowProc function. An application should return 0 if it processes this message. An application can process this message or pass it to the [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function to generate a matching [**WM\_KEYDOWN**](../inputdev/wm-keydown.md) message. Sent to an application by the IME to notify the application of a key release and to keep message order. A window receives this message through its WindowProc function. An application should return 0 if it processes this message. An application can process this message or pass it to the [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function to generate a matching [**WM\_KEYUP**](../inputdev/wm-keyup.md) message. Posted to a window when the cursor hovers over the nonclient area of the window for the period of time specified in a prior call to TrackMouseEvent. If an application processes this message, it should return zero. Hover tracking stops when this message is generated. The application must call [**TrackMouseEvent**](/windows/win32/api/winuser/nf-winuser-trackmouseevent) again if it requires further tracking of mouse hover behavior. You can also use the [**GET\_X\_LPARAM**](/windows/desktop/api/windowsx/nf-windowsx-get_x_lparam) and [**GET\_Y\_LPARAM**](/windows/desktop/api/windowsx/nf-windowsx-get_y_lparam) macros to extract the values of the x- and y- coordinates from *lParam*. This doc was truncated. Read more on docs.microsoft.com. Posted to a window when the cursor leaves the nonclient area of the window specified in a prior call to TrackMouseEvent. If an application processes this message, it should return zero. All tracking requested by [**TrackMouseEvent**](/windows/win32/api/winuser/nf-winuser-trackmouseevent) is canceled when this message is generated. The application must call **TrackMouseEvent** when the mouse reenters its window if it requires further tracking of mouse hover behavior. Sent when the effective dots per inch (dpi) for a window has changed. If an application processes this message, it should return zero. This message is only relevant for **PROCESS\_PER\_MONITOR\_DPI\_AWARE** applications or **DPI\_AWARENESS\_PER\_MONITOR\_AWARE** threads. It may be received on certain DPI changes if your top-level window or process is running as **DPI unaware** or **system DPI aware**, but in those situations it can be safely ignored. For more information about the different types of awareness, see [**PROCESS\_DPI\_AWARENESS**](/windows/desktop/api/ShellScalingApi/ne-shellscalingapi-process_dpi_awareness) and [**DPI\_AWARENESS**](/windows/desktop/api/windef/ne-windef-dpi_awareness). Older versions of Windows required DPI awareness to be tied at the level of an application. Those apps use **PROCESS\_DPI\_AWARENESS**. Currently, DPI awareness is tied to threads and individual windows rather than the entire application. These apps use **DPI\_AWARENESS**. You only need to use either the X-axis or the Y-axis value when scaling your application since they are the same. In order to handle this message correctly, you will need to resize and reposition your window based on the suggestions provided by *lParam* and using [**SetWindowPos**](/windows/desktop/api/winuser/nf-winuser-setwindowpos). If you do not do this, your window will grow or shrink with respect to everything else on the new monitor. For example, if a user is using multiple monitors and drags your window from a 96 DPI monitor to a 192 DPI monitor, your window will appear to be half as large with respect to other items on the 192 DPI monitor. The base value of DPI is defined as **USER\_DEFAULT\_SCREEN\_DPI** which is set to 96. To determine the scaling factor for a monitor, take the DPI value and divide by **USER\_DEFAULT\_SCREEN\_DPI**. The following table provides some sample DPI values and associated scaling factors. | DPI value | Scaling percentage | |-----------|--------------------| | 96 | 100% | | 120 | 125% | | 144 | 150% | | 192 | 200% | The following example provides a sample DPI change handler. This doc was truncated. Read more on docs.microsoft.com. For Per Monitor v2 top-level windows, this message is sent to all HWNDs in the child HWDN tree of the window that is undergoing a DPI change. | WM_DPICHANGED_BEFOREPARENT message (Winuser.h) This value is unused and ignored by the system. There is no default handling of this message in [DefWindowProc](/windows/win32/api/winuser/nf-winuser-defwindowproca). This message is only sent when the top-level window has a DPI awareness context of PMv2. Read more on docs.microsoft.com. For Per Monitor v2 top-level windows, this message is sent to all HWNDs in the child HWDN tree of the window that is undergoing a DPI change. | WM_DPICHANGED_AFTERPARENT message (Winuser.h) This value is unused and ignored by the system. There is no default handling of this message in [DefWindowProc](/windows/win32/api/winuser/nf-winuser-defwindowproca). This message is only sent when the top-level window has a DPI awareness context of PMv2. Read more on docs.microsoft.com. This message tells the operating system that the window will be sized to dimensions other than the default. The function returns a BOOL. Returning TRUE indicates that a new size has been computed. Returning FALSE indicates that the message will not be handled, and the default linear DPI scaling will apply to the window. This message is only sent to top-level windows which have a DPI awareness context of Per Monitor v2. This event is necessary to facilitate graceful non-linear scaling, and ensures that the windows's position remains constant in relationship to the cursor and when moving back and forth across monitors. There is no specific default handling of this message in [DefWindowProc](/windows/win32/api/winuser/nf-winuser-defwindowproca). As for all messages it does not explicitly handle, [DefWindowProc](/windows/win32/api/winuser/nf-winuser-defwindowproca) will return zero for this message. As noted above, this return tells the system to use the default linear behavior. Read more on docs.microsoft.com. An application sends a WM\_CUT message to an edit control or combo box to delete (cut) the current selection, if any, in the edit control and copy the deleted text to the clipboard in CF\_TEXT format. This message does not return a value. The deletion performed by the **WM\_CUT** message can be undone by sending the edit control an [**EM\_UNDO**](../controls/em-undo.md) message. To delete the current selection without placing the deleted text on the clipboard, use the [**WM\_CLEAR**](wm-clear.md) message. When sent to a combo box, the **WM\_CUT** message is handled by its edit control. This message has no effect when sent to a combo box with the [**CBS\_DROPDOWNLIST**](../controls/combo-box-styles.md) style. Read more on docs.microsoft.com. An application sends the WM\_COPY message to an edit control or combo box to copy the current selection to the clipboard in CF\_TEXT format. Returns nonzero value on success, else zero. When sent to a combo box, the **WM\_COPY** message is handled by its edit control. This message has no effect when sent to a combo box with the [**CBS\_DROPDOWNLIST**](../controls/combo-box-styles.md) style. An application sends a WM\_PASTE message to an edit control or combo box to copy the current content of the clipboard to the edit control at the current caret position. Data is inserted only if the clipboard contains data in CF\_TEXT format. This message does not return a value. When sent to a combo box, the **WM\_PASTE** message is handled by its edit control. This message has no effect when sent to a combo box with the [**CBS\_DROPDOWNLIST**](../controls/combo-box-styles.md) style. An application sends a WM\_CLEAR message to an edit control or combo box to delete (clear) the current selection, if any, from the edit control. This message does not return a value. The deletion performed by the **WM\_CLEAR** message can be undone by sending the edit control an [**EM\_UNDO**](../controls/em-undo.md) message. To delete the current selection and place the deleted content on the clipboard, use the [**WM\_CUT**](wm-cut.md) message. When sent to a combo box, the **WM\_CLEAR** message is handled by its edit control. This message has no effect when sent to a combo box with the [**CBS\_DROPDOWNLIST**](../controls/combo-box-styles.md) style. Read more on docs.microsoft.com. An application sends a WM\_UNDO message to an edit control to undo the last operation. When this message is sent to an edit control, the previously deleted text is restored or the previously added text is deleted. If the message succeeds, the return value is **TRUE**. If the message fails, the return value is **FALSE**. **Rich Edit:** It is recommended that [**EM\_UNDO**](em-undo.md) be used instead of **WM\_UNDO**. Sent to the clipboard owner if it has delayed rendering a specific clipboard format and if an application has requested data in that format. If an application processes this message, it should return zero. When responding to a **WM\_RENDERFORMAT** message, the clipboard owner must not open the clipboard before calling [**SetClipboardData**](/windows/win32/api/winuser/nf-winuser-setclipboarddata). Opening the clipboard is not necessary before placing data in response to **WM\_RENDERFORMAT**, and any attempt to open the clipboard will fail because the clipboard is currently being held open by the application that requested the format to be rendered. Sent to the clipboard owner before it is destroyed, if the clipboard owner has delayed rendering one or more clipboard formats. If an application processes this message, it should return zero. When responding to a **WM\_RENDERALLFORMATS** message, the application must call the [**OpenClipboard**](/windows/win32/api/winuser/nf-winuser-openclipboard) function and then check that it is still the clipboard owner by calling the [**GetClipboardOwner**](/windows/win32/api/winuser/nf-winuser-getclipboardowner) function before calling [**SetClipboardData**](/windows/win32/api/winuser/nf-winuser-setclipboarddata). The application needs to check that it is still the clipboard owner after opening the clipboard because after it receives the **WM\_RENDERALLFORMATS** message, but before it opens the clipboard, another application may have opened and taken ownership of the clipboard, and that application's data should not be overwritten. In most cases, the application should not call the [**EmptyClipboard**](/windows/win32/api/winuser/nf-winuser-emptyclipboard) function before calling [**SetClipboardData**](/windows/win32/api/winuser/nf-winuser-setclipboarddata), since doing so will erase the clipboard formats that the application has already rendered. When the application returns, the system removes any unrendered formats from the list of available clipboard formats. For information about delayed rendering, see [Delayed Rendering](clipboard-operations.md#delayed-rendering). Read more on docs.microsoft.com. Sent to the clipboard owner when a call to the EmptyClipboard function empties the clipboard. A window receives this message through its WindowProc function. If an application processes this message, it should return zero. Learn more about this API from docs.microsoft.com. Sent to the first window in the clipboard viewer chain when the content of the clipboard changes. This enables a clipboard viewer window to display the new content of the clipboard. A window receives this message through its WindowProc function. Only clipboard viewer windows receive this message. These are windows that have been added to the clipboard viewer chain by using the [**SetClipboardViewer**](/windows/desktop/api/Winuser/nf-winuser-setclipboardviewer) function. Each window that receives the **WM\_DRAWCLIPBOARD** message must call the [**SendMessage**](/windows/desktop/api/winuser/nf-winuser-sendmessage) function to pass the message on to the next window in the clipboard viewer chain. The handle to the next window in the chain is returned by [**SetClipboardViewer**](/windows/desktop/api/Winuser/nf-winuser-setclipboardviewer), and may change in response to a [**WM\_CHANGECBCHAIN**](wm-changecbchain.md) message. Read more on docs.microsoft.com. Sent to the clipboard owner by a clipboard viewer window when the clipboard contains data in the CF\_OWNERDISPLAY format and the clipboard viewer's client area needs repainting. If an application processes this message, it should return zero. To determine whether the entire client area or just a portion of it needs repainting, the clipboard owner must compare the dimensions of the drawing area given in the **rcPaint** member of [**PAINTSTRUCT**](/windows/win32/api/winuser/ns-winuser-paintstruct) to the dimensions given in the most recent [**WM\_SIZECLIPBOARD**](wm-sizeclipboard.md) message. The clipboard owner must use the [**GlobalLock**](/windows/desktop/api/winbase/nf-winbase-globallock) function to lock the memory that contains the [**PAINTSTRUCT**](/windows/win32/api/winuser/ns-winuser-paintstruct) structure. Before returning, the clipboard owner must unlock that memory by using the [**GlobalUnlock**](/windows/desktop/api/winbase/nf-winbase-globalunlock) function. Read more on docs.microsoft.com. Sent to the clipboard owner by a clipboard viewer window when the clipboard contains data in the CF\_OWNERDISPLAY format and an event occurs in the clipboard viewer's vertical scroll bar. If an application processes this message, it should return zero. The clipboard owner can use the [**ScrollWindow**](https://msdn.microsoft.com/library/Cc410994(v=MSDN.10).aspx) function to scroll the image in the clipboard viewer window and invalidate the appropriate region. Sent to the clipboard owner by a clipboard viewer window when the clipboard contains data in the CF\_OWNERDISPLAY format and the clipboard viewer's client area has changed size. If an application processes this message, it should return zero. When the clipboard viewer window is about to be destroyed or resized, a **WM\_SIZECLIPBOARD** message is sent with a null rectangle (0, 0, 0, 0) as the new size. This permits the clipboard owner to free its display resources. The clipboard owner must use the [**GlobalLock**](/windows/desktop/api/winbase/nf-winbase-globallock) function to lock the memory object that contains [**RECT**](/windows/win32/api/windef/ns-windef-rect). Before returning, the clipboard owner must unlock the object by using the [**GlobalUnlock**](/windows/desktop/api/winbase/nf-winbase-globalunlock) function. Read more on docs.microsoft.com. Sent to the clipboard owner by a clipboard viewer window to request the name of a CF\_OWNERDISPLAY clipboard format. If an application processes this message, it should return zero. In response to this message, the clipboard owner should copy the name of the owner-display format to the specified buffer, not exceeding the buffer size specified by the *wParam* parameter. A clipboard viewer window sends this message to the clipboard owner to determine the name of the [**CF\_OWNERDISPLAY**](standard-clipboard-formats.md) format for example, to initialize a menu listing available formats. Read more on docs.microsoft.com. Sent to the first window in the clipboard viewer chain when a window is being removed from the chain. A window receives this message through its WindowProc function. If an application processes this message, it should return zero. Each clipboard viewer window saves the handle to the next window in the clipboard viewer chain. Initially, this handle is the return value of the [**SetClipboardViewer**](/windows/desktop/api/Winuser/nf-winuser-setclipboardviewer) function. When a clipboard viewer window receives the **WM\_CHANGECBCHAIN** message, it should call the [**SendMessage**](/windows/desktop/api/winuser/nf-winuser-sendmessage) function to pass the message to the next window in the chain, unless the next window is the window being removed. In this case, the clipboard viewer should save the handle specified by the *lParam* parameter as the next window in the chain. Read more on docs.microsoft.com. Sent to the clipboard owner by a clipboard viewer window. If an application processes this message, it should return zero. The clipboard owner can use the [**ScrollWindow**](https://msdn.microsoft.com/library/Cc410994(v=MSDN.10).aspx) function to scroll the image in the clipboard viewer window and invalidate the appropriate region. The WM\_QUERYNEWPALETTE message informs a window that it is about to receive the keyboard focus, giving the window the opportunity to realize its logical palette when it receives the focus. If the window realizes its logical palette, it must return **TRUE**; otherwise, it must return **FALSE**. Learn more about this API from docs.microsoft.com. The WM\_PALETTEISCHANGING message informs applications that an application is going to realize its logical palette. If an application processes this message, it should return zero. The application changing its palette does not wait for acknowledgment of this message before changing the palette and sending the [**WM\_PALETTECHANGED**](wm-palettechanged.md) message. As a result, the palette may already be changed by the time an application receives this message. If the application either ignores or fails to process this message and a second application realizes its palette while the first is using palette indexes, there is a strong possibility that the user will see unexpected colors during subsequent drawing operations. Read more on docs.microsoft.com. The WM\_PALETTECHANGED message is sent to all top-level and overlapped windows after the window with the keyboard focus has realized its logical palette, thereby changing the system palette. This message must be sent to all top-level and overlapped windows, including the one that changed the system palette. If any child windows use a color palette, this message must be passed on to them as well. To avoid creating an infinite loop, a window that receives this message must not realize its palette, unless it determines that *wParam* does not contain its own window handle. Read more on docs.microsoft.com. Posted when the user presses a hot key registered by the RegisterHotKey function. The message is placed at the top of the message queue associated with the thread that registered the hot key. **WM\_HOTKEY** is unrelated to the [**WM\_GETHOTKEY**](wm-gethotkey.md) and [**WM\_SETHOTKEY**](wm-sethotkey.md) hot keys. The **WM\_HOTKEY** message is sent for generic hot keys while the **WM\_SETHOTKEY** and **WM\_GETHOTKEY** messages relate to window activation hot keys. The WM\_PRINT message is sent to a window to request that it draw itself in the specified device context, most commonly in a printer device context. The [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) function processes this message based on which drawing option is specified: if PRF\_CHECKVISIBLE is specified and the window is not visible, do nothing, if PRF\_NONCLIENT is specified, draw the nonclient area in the specified device context, if PRF\_ERASEBKGND is specified, send the window a [**WM\_ERASEBKGND**](../winmsg/wm-erasebkgnd.md) message, if PRF\_CLIENT is specified, send the window a [**WM\_PRINTCLIENT**](wm-printclient.md) message, if PRF\_CHILDREN is set, send each visible child window a **WM\_PRINT** message, if PRF\_OWNED is set, send each visible owned window a **WM\_PRINT** message. Notifies a window that the user generated an application command event, for example, by clicking an application command button using the mouse or typing an application command key on the keyboard. If an application processes this message, it should return **TRUE**. For more information about processing the return value, see the Remarks section. [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) generates the **WM\_APPCOMMAND** message when it processes the [**WM\_XBUTTONUP**](wm-xbuttonup.md) or [**WM\_NCXBUTTONUP**](wm-ncxbuttonup.md) message, or when the user types an application command key. If a child window does not process this message and instead calls [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca), **DefWindowProc** will send the message to its parent window. If a top level window does not process this message and instead calls **DefWindowProc**, **DefWindowProc** will call a shell hook with the hook code equal to **HSHELL\_APPCOMMAND**. To get the coordinates of the cursor if the message was generated by a mouse click, the application can call [**GetMessagePos**](/windows/desktop/api/winuser/nf-winuser-getmessagepos). An application can test whether the message was generated by the mouse by checking whether *lParam* contains **FAPPCOMMAND\_MOUSE**. Unlike other windows messages, an application should return **TRUE** from this message if it processes it. Doing so will allow software that simulates this message on Windows systems earlier than Windows 2000 to determine whether the window procedure processed the message or called [**DefWindowProc**](/windows/desktop/api/winuser/nf-winuser-defwindowproca) to process it. Read more on docs.microsoft.com. Broadcast to every window following a theme change event. Examples of theme change events are the activation of a theme, the deactivation of a theme, or a transition from one theme to another. Type: **LRESULT** If an application processes this message, it should return zero. A window receives this message through its [**WindowProc**](/previous-versions/windows/desktop/legacy/ms633573(v=vs.85)) function. > [!Note] > This message is posted by the operating system. Applications typically do not send this message. Themes are specifications for the appearance of controls, so that the visual element of a control is treated separately from its functionality. To release an existing theme handle, call [**CloseThemeData**](/windows/win32/api/uxtheme/nf-uxtheme-closethemedata). To acquire a new theme handle, use [**OpenThemeData**](/windows/win32/api/uxtheme/nf-uxtheme-openthemedata). Following the **WM\_THEMECHANGED** broadcast, any existing theme handles are invalid. A theme-aware window should release and reopen any of its pre-existing theme handles when it receives the **WM\_THEMECHANGED** message. If the [**OpenThemeData**](/windows/win32/api/uxtheme/nf-uxtheme-openthemedata) function returns **NULL**, the window should paint unthemed. Read more on docs.microsoft.com. Sent when the contents of the clipboard have changed. If an application processes this message, it should return zero. To register a window to receive this message, use the [**AddClipboardFormatListener**](/windows/desktop/api/Winuser/nf-winuser-addclipboardformatlistener) function. Informs all top-level windows that Desktop Window Manager (DWM) composition has been enabled or disabled. If an application processes this message, it should return zero. A window receives this message through its [**WindowProc**](/previous-versions/windows/desktop/legacy/ms633573(v=vs.85)) function. The [**DwmIsCompositionEnabled**](/windows/desktop/api/Dwmapi/nf-dwmapi-dwmiscompositionenabled) function can be used to determine the current composition state. Read more on docs.microsoft.com. Sent when the non-client area rendering policy has changed. If an application processes this message, it should return zero. A window receives this message through its [**WindowProc**](/previous-versions/windows/desktop/legacy/ms633573(v=vs.85)) function. The [**DwmGetWindowAttribute**](/windows/desktop/api/Dwmapi/nf-dwmapi-dwmgetwindowattribute) and [**DwmSetWindowAttribute**](/windows/desktop/api/Dwmapi/nf-dwmapi-dwmsetwindowattribute) functions are used to get or set the non-client rendering policy. Read more on docs.microsoft.com. Informs all top-level windows that the colorization color has changed. If an application processes this message, it should return zero. A window receives this message through its [**WindowProc**](/previous-versions/windows/desktop/legacy/ms633573(v=vs.85)) function. [**DwmGetColorizationColor**](/windows/desktop/api/Dwmapi/nf-dwmapi-dwmgetcolorizationcolor) is used to determine the current color value. Read more on docs.microsoft.com. Sent when a Desktop Window Manager (DWM) composed window is maximized. If an application processes this message, it should return zero. A window receives this message through its [**WindowProc**](/previous-versions/windows/desktop/legacy/ms633573(v=vs.85)) function. Instructs a window to provide a static bitmap to use as a thumbnail representation of that window. If an application processes this message, it should return zero. DWM sends this message to a window if all of the following situations are true: - DWM is displaying an iconic representation of the window. - The [**DWMWA\_HAS\_ICONIC\_BITMAP**](/windows/desktop/api/Dwmapi/ne-dwmapi-dwmwindowattribute) attribute is set on the window. - The window did not set a cached bitmap. - There is room in the cache for another bitmap. The window that receives this message should respond by generating a bitmap that is not larger than the size that is requested in the message parameters. The window then calls the [**DwmSetIconicThumbnail**](/windows/desktop/api/Dwmapi/nf-dwmapi-dwmseticonicthumbnail) function to override the default thumbnail. If the window does not supply a bitmap in a given amount of time, DWM uses its own default iconic representation for the window. The window must belong to the calling process. Read more on docs.microsoft.com. Instructs a window to provide a static bitmap to use as a live preview (also known as a Peek preview) of that window. If an application processes this message, it should return zero. A *live preview* (also known as a *Peek preview*) of a window appears when a user moves the mouse pointer over the window's thumbnail in the taskbar or gives the thumbnail focus in the ALT+TAB window. This view is a full-sized preview of the window and can be a live snapshot or an iconic representation. Desktop Window Manager (DWM) sends this message to a window if all of the following situations are true: - Live preview has been invoked on the window. - The [**DWMWA\_HAS\_ICONIC\_BITMAP**](/windows/desktop/api/Dwmapi/ne-dwmapi-dwmwindowattribute) attribute is set on the window. - An iconic representation is the only one that exists for this window. The window that receives this message should respond by generating a full-scale bitmap. The window then calls the [**DwmSetIconicLivePreviewBitmap**](/windows/desktop/api/Dwmapi/nf-dwmapi-dwmseticoniclivepreviewbitmap) function to set the live preview. If the window does not set a bitmap in a given amount of time, DWM uses its own default iconic representation for the window. Read more on docs.microsoft.com. Sent to request extended title bar information. A window receives this message through its WindowProc function. The following example shows how the message receiver casts an **LPARAM** value to retrieve the [**TITLEBARINFOEX**](/windows/win32/api/winuser/ns-winuser-titlebarinfoex) structure. `TITLEBARINFOEX *ptinfo = (TITLEBARINFOEX *)lParam;` Read more on docs.microsoft.com. Used to define private messages, usually of the form WM\_APP+x, where x is an integer value. The **WM\_APP** constant is used to distinguish between message values that are reserved for use by the system and values that can be used by an application to send messages within a private window class. The following are the ranges of message numbers available. | Range | Meaning | |-------------------------------------------------------|----------------------------------------------------------------| | 0 through [**WM\_USER**](wm-user.md) –1
| Messages reserved for use by the system.
| | [**WM\_USER**](wm-user.md) through 0x7FFF
| Integer messages for use by private window classes.
| | **WM\_APP** through 0xBFFF
| Messages available for use by applications.
| | 0xC000 through 0xFFFF
| String messages for use by applications.
| | Greater than 0xFFFF
| Reserved by the system.
| Message numbers in the first range (0 through [**WM\_USER**](wm-user.md) –1) are defined by the system. Values in this range that are not explicitly defined are reserved by the system. Message numbers in the second range ([**WM\_USER**](wm-user.md) through 0x7FFF) can be defined and used by an application to send messages within a private window class. These values cannot be used to define messages that are meaningful throughout an application because some predefined window classes already define values in this range. For example, predefined control classes such as **BUTTON**, **EDIT**, **LISTBOX**, and **COMBOBOX** may use these values. Messages in this range should not be sent to other applications unless the applications have been designed to exchange messages and to attach the same meaning to the message numbers. Message numbers in the third range (0x8000 through 0xBFFF) are available for applications to use as private messages. Messages in this range do not conflict with system messages. Message numbers in the fourth range (0xC000 through 0xFFFF) are defined at run time when an application calls the [**RegisterWindowMessage**](/windows/win32/api/winuser/nf-winuser-registerwindowmessagea) function to retrieve a message number for a string. All applications that register the same string can use the associated message number for exchanging messages. The actual message number, however, is not a constant and cannot be assumed to be the same between different sessions. Message numbers in the fifth range (greater than 0xFFFF) are reserved by the system. Read more on docs.microsoft.com. Used to define private messages for use by private window classes, usually of the form WM\_USER+x, where x is an integer value. The following are the ranges of message numbers. | Range | Meaning | |--------------------------------------------------------------|----------------------------------------------------------------| | 0 through **WM\_USER** –1
| Messages reserved for use by the system.
| | **WM\_USER** through 0x7FFF
| Integer messages for use by private window classes.
| | [**WM\_APP**](wm-app.md) (0x8000) through 0xBFFF
| Messages available for use by applications.
| | 0xC000 through 0xFFFF
| String messages for use by applications.
| | Greater than 0xFFFF
| Reserved by the system.
| Message numbers in the first range (0 through **WM\_USER** –1) are defined by the system. Values in this range that are not explicitly defined are reserved by the system. Message numbers in the second range (**WM\_USER** through 0x7FFF) can be defined and used by an application to send messages within a private window class. These values cannot be used to define messages that are meaningful throughout an application because some predefined window classes already define values in this range. For example, predefined control classes such as **BUTTON**, **EDIT**, **LISTBOX**, and **COMBOBOX** may use these values. Messages in this range should not be sent to other applications unless the applications have been designed to exchange messages and to attach the same meaning to the message numbers. Message numbers in the third range (0x8000 through 0xBFFF) are available for applications to use as private messages. Messages in this range do not conflict with system messages. Message numbers in the fourth range (0xC000 through 0xFFFF) are defined at run time when an application calls the [**RegisterWindowMessage**](/windows/win32/api/winuser/nf-winuser-registerwindowmessagea) function to retrieve a message number for a string. All applications that register the same string can use the associated message number for exchanging messages. The actual message number, however, is not a constant and cannot be assumed to be the same between different sessions. Message numbers in the fifth range (greater than 0xFFFF) are reserved by the system. Read more on docs.microsoft.com. The WM\_CAP\_SET\_CALLBACK\_ERROR message sets an error callback function in the client application. AVICap calls this procedure when errors occur. You can send this message explicitly or by using the capSetCallbackOnError macro. *fpProc* Pointer to the error callback function, of type [**capErrorCallback**](/windows/desktop/api/Vfw/nc-vfw-caperrorcallbacka). Specify **NULL** for this parameter to disable a previously installed error callback function. Returns **TRUE** if successful or **FALSE** if streaming capture or a single-frame capture session is in progress. Applications can optionally set an error callback function. If set, AVICap calls the error procedure in the following situations: - The disk is full. - A capture window cannot be connected with a capture driver. - A waveform-audio device cannot be opened. - The number of frames dropped during capture exceeds the specified percentage. - The frames cannot be captured due to vertical synchronization interrupt problems. Read more on docs.microsoft.com. The WM\_CAP\_SET\_CALLBACK\_STATUS message sets a status callback function in the application. AVICap calls this procedure whenever the capture window status changes. You can send this message explicitly or by using the capSetCallbackOnStatus macro. *fpProc* Pointer to the status callback function, of type [**capStatusCallback**](/windows/desktop/api/Vfw/nc-vfw-capstatuscallbacka). Specify **NULL** for this parameter to disable a previously installed status callback function. Returns **TRUE** if successful or **FALSE** if streaming capture or a single-frame capture session is in progress. Applications can optionally set a status callback function. If set, AVICap calls this procedure in the following situations: - A capture session is completed. - A capture driver successfully connected to a capture window. - An optimal palette is created. - The number of captured frames is reported. Read more on docs.microsoft.com. The WM\_CAP\_SET\_CALLBACK\_YIELD message sets a callback function in the application. AVICap calls this procedure when the capture window yields during streaming capture. You can send this message explicitly or by using the capSetCallbackOnYield macro. *fpProc* Pointer to the yield callback function, of type [**capYieldCallback**](/windows/desktop/api/Vfw/nc-vfw-capyieldcallback). Specify **NULL** for this parameter to disable a previously installed yield callback function. Returns **TRUE** if successful or **FALSE** if streaming capture or a single-frame capture session is in progress. Applications can optionally set a yield callback function. The yield callback function is called at least once for each video frame captured during streaming capture. If a yield callback function is installed, it will be called regardless of the state of the **fYield** member of the [**CAPTUREPARMS**](/windows/win32/api/vfw/ns-vfw-captureparms) structure. If the yield callback function is used, it must be installed before starting the capture session and it must remain enabled for the duration of the session. It can be disabled after streaming capture ends. Applications typically perform some type of message processing in the callback function consisting of a [PeekMessage](/windows/win32/api/winuser/nf-winuser-peekmessagea), [TranslateMessage](/windows/win32/api/winuser/nf-winuser-translatemessage), [DispatchMessage](/windows/win32/api/winuser/nf-winuser-dispatchmessage) loop, as in the message loop of a [WinMain](/windows/win32/api/winbase/nf-winbase-winmain) function. The yield callback function must also filter and remove messages that can cause reentrancy problems. An application typically returns **TRUE** in the yield procedure to continue streaming capture. If a yield callback function returns **FALSE**, the capture window stops the capture process. Read more on docs.microsoft.com. The WM\_CAP\_SET\_CALLBACK\_FRAME message sets a preview callback function in the application. AVICap calls this procedure when the capture window captures preview frames. You can send this message explicitly or by using the capSetCallbackOnFrame macro. *fpProc* Pointer to the preview callback function, of type [**capVideoStreamCallback**](/windows/desktop/api/Vfw/nc-vfw-capvideocallback). Specify **NULL** for this parameter to disable a previously installed callback function. Returns **TRUE** if successful or **FALSE** if streaming capture or a single-frame capture session is in progress. The capture window calls the callback function before displaying preview frames. This allows an application to modify the frame if desired. This callback function is not used during streaming video capture. The WM\_CAP\_SET\_CALLBACK\_VIDEOSTREAM message sets a callback function in the application. *fpProc* Pointer to the video-stream callback function, of type [**capVideoStreamCallback**](/windows/desktop/api/Vfw/nc-vfw-capvideocallback). Specify **NULL** for this parameter to disable a previously installed video-stream callback function. Returns **TRUE** if successful or **FALSE** if streaming capture or a single-frame capture session is in progress. The capture window calls the callback function before writing the captured frame to disk. This allows applications to modify the frame if desired. If a video stream callback function is used for streaming capture, the procedure must be installed before starting the capture session and it must remain enabled for the duration of the session. It can be disabled after streaming capture ends. Read more on docs.microsoft.com. The WM\_CAP\_SET\_CALLBACK\_WAVESTREAM message sets a callback function in the application. *fpProc* Pointer to the wave stream callback function, of type [**capWaveStreamCallback**](/windows/desktop/api/Vfw/nc-vfw-capwavecallback). Specify **NULL** for this parameter to disable a previously installed wave stream callback function. Returns **TRUE** if successful or **FALSE** if streaming capture or a single-frame capture session is in progress. The capture window calls the procedure before writing the audio buffer to disk. This allows applications to modify the audio buffer if desired. If a wave stream callback function is used, it must be installed before starting the capture session and it must remain enabled for the duration of the session. It can be disabled after streaming capture ends. Read more on docs.microsoft.com. The WM\_CAP\_GET\_USER\_DATA message retrieves a LONG\_PTR data value associated with a capture window. You can send this message explicitly or by using the capGetUserData macro. Returns a value previously saved by using the [**WM\_CAP\_SET\_USER\_DATA**](wm-cap-set-user-data.md) message. Learn more about this API from docs.microsoft.com. The WM\_CAP\_SET\_USER\_DATA message associates a LONG\_PTR data value with a capture window. You can send this message explicitly or by using the capSetUserData macro. *lUser* Data value to associate with a capture window. Returns **TRUE** if successful or **FALSE** if streaming capture is in progress. Typically this message is used to point to a block of data associated with a capture window. The WM\_CAP\_DRIVER\_CONNECT message connects a capture window to a capture driver. You can send this message explicitly or by using the capDriverConnect macro. *iIndex* Index of the capture driver. The index can range from 0 through 9. Returns **TRUE** if successful or **FALSE** if the specified capture driver cannot be connected to the capture window. Connecting a capture driver to a capture window automatically disconnects any previously connected capture driver. The WM\_CAP\_DRIVER\_DISCONNECT message disconnects a capture driver from a capture window. You can send this message explicitly or by using the capDriverDisconnect macro. Returns **TRUE** if successful or **FALSE** if the capture window is not connected to a capture driver. Learn more about this API from docs.microsoft.com. The WM\_CAP\_DRIVER\_GET\_NAME message returns the name of the capture driver connected to the capture window. You can send this message explicitly or by using the capDriverGetName macro. *wSize* Size, in bytes, of the buffer referenced by**szName**. *szName* Pointer to an application-defined buffer used to return the device name as a null-terminated string. Returns **TRUE** if successful or **FALSE** if the capture window is not connected to a capture driver. The name is a text string retrieved from the driver's resource area. Applications should allocate approximately 80 bytes for this string. If the driver does not contain a name resource, the full path name of the driver listed in the registry or in the SYSTEM.INI file is returned. The WM\_CAP\_DRIVER\_GET\_VERSION message returns the version information of the capture driver connected to a capture window. You can send this message explicitly or by using the capDriverGetVersion macro. *wSize* Size, in bytes, of the application-defined buffer referenced by**szVer**. *szVer* Pointer to an application-defined buffer used to return the version information as a null-terminated string. Returns **TRUE** if successful or **FALSE** if the capture window is not connected to a capture driver. The version information is a text string retrieved from the driver's resource area. Applications should allocate approximately 40 bytes for this string. If version information is not available, a **NULL** string is returned. The WM\_CAP\_DRIVER\_GET\_CAPS message returns the hardware capabilities of the capture driver currently connected to a capture window. You can send this message explicitly or by using the capDriverGetCaps macro. *wSize* Size, in bytes, of the structure referenced by**s**. *psCaps* Pointer to the [**CAPDRIVERCAPS**](/windows/win32/api/vfw/ns-vfw-capdrivercaps) structure to contain the hardware capabilities. Returns **TRUE** if successful or **FALSE** if the capture window is not connected to a capture driver. The capabilities returned in [**CAPDRIVERCAPS**](/windows/win32/api/vfw/ns-vfw-capdrivercaps) are constant for a given capture driver. Applications need to retrieve this information once when the capture driver is first connected to a capture window. The WM\_CAP\_FILE\_SET\_CAPTURE\_FILE message names the file used for video capture. You can send this message explicitly or by using the capFileSetCaptureFile macro. *szName* Pointer to the null-terminated string that contains the name of the capture file to use. Returns **TRUE** if successful or **FALSE** if the filename is invalid, or if streaming or single-frame capture is in progress. This message stores the filename in an internal structure. It does not create, allocate, or open the specified file. The default capture filename is C:\\CAPTURE.AVI. The WM\_CAP\_FILE\_GET\_CAPTURE\_FILE message returns the name of the current capture file. You can send this message explicitly or by using the capFileGetCaptureFile macro. *wSize* Size, in bytes, of the application-defined buffer referenced by**szName**. *szName* Pointer to an application-defined buffer used to return the name of the capture file as a null-terminated string. Returns **TRUE** if successful or **FALSE** otherwise. The default capture filename is C:\\CAPTURE.AVI. The WM\_CAP\_FILE\_SAVEAS message copies the contents of the capture file to another file. You can send this message explicitly or by using the capFileSaveAs macro. *szName* Pointer to the null-terminated string that contains the name of the destination file used to copy the file. Returns **TRUE** if successful or **FALSE** otherwise. If an error occurs and an error callback function is set using the [**WM\_CAP\_SET\_CALLBACK\_ERROR**](wm-cap-set-callback-error.md) message, the error callback function is called. This message does not change the name or contents of the current capture file. If the copy operation is unsuccessful due to a disk full error, the destination file is automatically deleted. Typically, a capture file is preallocated for the largest capture segment anticipated and only a portion of it might be used to capture data. This message copies only the portion of the file containing the capture data. Read more on docs.microsoft.com. The WM\_CAP\_FILE\_SAVEDIB message copies the current frame to a DIB file. You can send this message explicitly or by using the capFileSaveDIB macro. *szName* Pointer to the null-terminated string that contains the name of the destination DIB file. Returns **TRUE** if successful or **FALSE** otherwise. If an error occurs and an error callback function is set using the [**WM\_CAP\_SET\_CALLBACK\_ERROR**](wm-cap-set-callback-error.md) message, the error callback function is called. If the capture driver supplies frames in a compressed format, this call attempts to decompress the frame before writing the file. The WM\_CAP\_FILE\_ALLOCATE message creates (preallocates) a capture file of a specified size. You can send this message explicitly or by using the capFileAlloc macro. *dwSize* Size, in bytes, to create the capture file. Returns **TRUE** if successful or **FALSE** otherwise. If an error occurs and an error callback function is set using the [**WM\_CAP\_SET\_CALLBACK\_ERROR**](wm-cap-set-callback-error.md) message, the error callback function is called. You can improve streaming capture performance significantly by preallocating a capture file large enough to store an entire video clip and by defragmenting the capture file before capturing the clip. The WM\_CAP\_FILE\_SET\_INFOCHUNK message sets and clears information chunks. *lpInfoChunk* Pointer to a [**CAPINFOCHUNK**](/windows/win32/api/vfw/ns-vfw-capinfochunk) structure defining the information chunk to be created or deleted. Returns **TRUE** if successful or **FALSE** otherwise. If an error occurs and an error callback function is set using the [**WM\_CAP\_SET\_CALLBACK\_ERROR**](wm-cap-set-callback-error.md) message, the error callback function is called. Multiple registered information chunks can be added to an AVI file. After an information chunk is set, it continues to be added to subsequent capture files until either the entry is cleared or all information chunk entries are cleared. To clear a single entry, specify the information chunk in the **fccInfoID** member and **NULL** in the **lpData** member of the [**CAPINFOCHUNK**](/windows/win32/api/vfw/ns-vfw-capinfochunk) structure. To clear all entries, specify **NULL** in **fccInfoID**. The WM\_CAP\_EDIT\_COPY message copies the contents of the video frame buffer and associated palette to the clipboard. You can send this message explicitly or by using the capEditCopy macro. Returns **TRUE** if successful or **FALSE** otherwise. Learn more about this API from docs.microsoft.com. The WM\_CAP\_SET\_AUDIOFORMAT message sets the audio format to use when performing streaming or step capture. You can send this message explicitly or by using the capSetAudioFormat macro. *wSize* Size, in bytes, of the structure referenced by **s**. *psAudioFormat* Pointer to a [**WAVEFORMATEX**](/windows/win32/api/mmeapi/ns-mmeapi-waveformatex) or [**PCMWAVEFORMAT**](/windows/win32/api/mmreg/ns-mmreg-pcmwaveformat) structure that defines the audio format. Returns **TRUE** if successful or **FALSE** otherwise. Learn more about this API from docs.microsoft.com. The WM\_CAP\_GET\_AUDIOFORMAT message obtains the audio format or the size of the audio format. You can send this message explicitly or by using the capGetAudioFormat and capGetAudioFormatSize macros. *wSize* Size, in bytes, of the structure referenced by**s**. *psAudioFormat* Pointer to a [**WAVEFORMATEX**](/windows/win32/api/mmeapi/ns-mmeapi-waveformatex) structure, or **NULL**. If the value is **NULL**, the size, in bytes, required to hold the structure is returned. Returns the size, in bytes, of the audio format. Because compressed audio formats vary in size requirements applications must first retrieve the size, then allocate memory, and finally request the audio format data. The WM\_CAP\_DLG\_VIDEOFORMAT message displays a dialog box in which the user can select the video format. Returns **TRUE** if successful or **FALSE** otherwise. After this message returns, applications might need to update the [**CAPSTATUS**](/windows/win32/api/vfw/ns-vfw-capstatus) structure because the user might have changed the image dimensions. The Video Format dialog box is unique for each capture driver. Some capture drivers might not support a Video Format dialog box. Applications can determine if the capture driver supports this message by checking the **fHasDlgVideoFormat** member of [**CAPDRIVERCAPS**](/windows/win32/api/vfw/ns-vfw-capdrivercaps). Read more on docs.microsoft.com. The WM\_CAP\_DLG\_VIDEOSOURCE message displays a dialog box in which the user can control the video source. Returns **TRUE** if successful or **FALSE** otherwise. The Video Source dialog box is unique for each capture driver. Some capture drivers might not support a Video Source dialog box. Applications can determine if the capture driver supports this message by checking the **fHasDlgVideoSource** member of the [**CAPDRIVERCAPS**](/windows/win32/api/vfw/ns-vfw-capdrivercaps) structure. The WM\_CAP\_DLG\_VIDEODISPLAY message displays a dialog box in which the user can set or adjust the video output. Returns **TRUE** if successful or **FALSE** otherwise. The controls in this dialog box do not affect digitized video data; they affect only the output or redisplay of the video signal. The Video Display dialog box is unique for each capture driver. Some capture drivers might not support a Video Display dialog box. Applications can determine if the capture driver supports this message by checking the **fHasDlgVideoDisplay** member of the [**CAPDRIVERCAPS**](/windows/win32/api/vfw/ns-vfw-capdrivercaps) structure. Read more on docs.microsoft.com. The WM\_CAP\_GET\_VIDEOFORMAT message retrieves a copy of the video format in use or the size required for the video format. You can send this message explicitly or by using the capGetVideoFormat and capGetVideoFormatSize macros. *wSize* Size, in bytes, of the structure referenced by**s**. *psVideoFormat* Pointer to a [**BITMAPINFO**](/windows/win32/api/wingdi/ns-wingdi-bitmapinfo) structure. You can also specify **NULL** to retrieve the number of bytes needed. Returns the size, in bytes, of the video format or zero if the capture window is not connected to a capture driver. For video formats that require a palette, the current palette is also returned. Because compressed video formats vary in size requirements applications must first retrieve the size, then allocate memory, and finally request the video format data. The WM\_CAP\_SET\_VIDEOFORMAT message sets the format of captured video data. You can send this message explicitly or by using the capSetVideoFormat macro. *wSize* Size, in bytes, of the structure referenced by **s**. *psVideoFormat* Pointer to a [**BITMAPINFO**](/windows/win32/api/wingdi/ns-wingdi-bitmapinfo) structure. Returns **TRUE** if successful or **FALSE** otherwise. Because video formats are device-specific, applications should check the return value from this function to determine if the format is accepted by the driver. The WM\_CAP\_DLG\_VIDEOCOMPRESSION message displays a dialog box in which the user can select a compressor to use during the capture process. Returns **TRUE** if successful or **FALSE** otherwise. Use this message with capture drivers that provide frames only in the BI\_RGB format. This message is most useful in the step capture operation to combine capture and compression in a single operation. Compressing frames with a software compressor as part of a real-time capture operation is most likely too time-consuming to perform. Compression does not affect the frames copied to the clipboard. Read more on docs.microsoft.com. The WM\_CAP\_SET\_PREVIEW message enables or disables preview mode. *f* Preview flag. Specify **TRUE** for this parameter to enable preview mode or **FALSE** to disable it. Returns **TRUE** if successful or **FALSE** otherwise. The preview mode uses substantial CPU resources. Applications can disable preview or lower the preview rate when another application has the focus. The **fLiveWindow** member of the [**CAPSTATUS**](/windows/win32/api/vfw/ns-vfw-capstatus) structure indicates if preview mode is currently enabled. Enabling preview mode automatically disables overlay mode. Read more on docs.microsoft.com. The WM\_CAP\_SET\_OVERLAY message enables or disables overlay mode. In overlay mode, video is displayed using hardware overlay. You can send this message explicitly or by using the capOverlay macro. *f* Overlay flag. Specify **TRUE** for this parameter to enable overlay mode or **FALSE** to disable it. Returns **TRUE** if successful or **FALSE** otherwise. Using an overlay does not require CPU resources. The **fHasOverlay** member of the [**CAPDRIVERCAPS**](/windows/win32/api/vfw/ns-vfw-capdrivercaps) structure indicates whether the device is capable of overlay. The **fOverlayWindow** member of the [**CAPSTATUS**](/windows/win32/api/vfw/ns-vfw-capstatus) structure indicates whether overlay mode is currently enabled. Enabling overlay mode automatically disables preview mode. Read more on docs.microsoft.com. The WM\_CAP\_SET\_PREVIEWRATE message sets the frame display rate in preview mode. You can send this message explicitly or by using the capPreviewRate macro. *wMS* Rate, in milliseconds, at which new frames are captured and displayed. Returns **TRUE** if successful or **FALSE** if the capture window is not connected to a capture driver. The preview mode uses substantial CPU resources. Applications can disable preview or lower the preview rate when another application has the focus. During streaming video capture, the previewing task is lower priority than writing frames to disk, and preview frames are displayed only if no other buffers are available for writing. The WM\_CAP\_SET\_SCALE message enables or disables scaling of the preview video images. *f* Preview scaling flag. Specify **TRUE** for this parameter to stretch preview frames to the size of the capture window or **FALSE** to display them at their natural size. Returns **TRUE** if successful or **FALSE** otherwise. Scaling preview images controls the immediate presentation of captured frames within the capture window. It has no effect on the size of the frames saved to file. Scaling has no effect when using overlay to display video in the frame buffer. Read more on docs.microsoft.com. The WM\_CAP\_GET\_STATUS message retrieves the status of the capture window. You can send this message explicitly or by using the capGetStatus macro. *wSize* Size, in bytes, of the structure referenced by**s**. *s* Pointer to a [**CAPSTATUS**](/windows/win32/api/vfw/ns-vfw-capstatus) structure. Returns **TRUE** if successful or **FALSE** if the capture window is not connected to a capture driver. The [**CAPSTATUS**](/windows/win32/api/vfw/ns-vfw-capstatus) structure contains the current state of the capture window. Since this state is dynamic and changes in response to various messages, the application should initialize this structure after sending the [**WM\_CAP\_DLG\_VIDEOFORMAT**](wm-cap-dlg-videoformat.md) message (or using the [**capDlgVideoFormat**](/windows/desktop/api/Vfw/nf-vfw-capdlgvideoformat) macro) and whenever it needs to enable menu items or determine the actual state of the window. The WM\_CAP\_SET\_SCROLL message defines the portion of the video frame to display in the capture window. *lpP* Address to contain the desired scroll position. Returns **TRUE** if successful or **FALSE** otherwise. The scroll position affects the image in both preview and overlay modes. The WM\_CAP\_GRAB\_FRAME message retrieves and displays a single frame from the capture driver. After capture, overlay and preview are disabled. You can send this message explicitly or by using the capGrabFrame macro. Returns **TRUE** if successful or **FALSE** otherwise. For information about installing callback functions, see the [**WM\_CAP\_SET\_CALLBACK\_ERROR**](wm-cap-set-callback-error.md) and [**WM\_CAP\_SET\_CALLBACK\_FRAME**](wm-cap-set-callback-frame.md) messages. The WM\_CAP\_GRAB\_FRAME\_NOSTOP message fills the frame buffer with a single uncompressed frame from the capture device and displays it. Returns **TRUE** if successful or **FALSE** otherwise. For information about installing callback functions, see the [**WM\_CAP\_SET\_CALLBACK\_ERROR**](wm-cap-set-callback-error.md) and [**WM\_CAP\_SET\_CALLBACK\_FRAME**](wm-cap-set-callback-frame.md) messages. The WM\_CAP\_SEQUENCE message initiates streaming video and audio capture to a file. You can send this message explicitly or by using the capCaptureSequence macro. Returns **TRUE** if successful or **FALSE** otherwise. If an error occurs and an error callback function is set using the [**WM\_CAP\_SET\_CALLBACK\_ERROR**](wm-cap-set-callback-error.md) message, the error callback function is called. If you want to alter the parameters controlling streaming capture, use the [**WM\_CAP\_SET\_SEQUENCE\_SETUP**](wm-cap-set-sequence-setup.md) message prior to starting the capture. By default, the capture window does not allow other applications to continue running during capture. To override this, either set the **fYield** member of the [**CAPTUREPARMS**](/windows/win32/api/vfw/ns-vfw-captureparms) structure to **TRUE**, or install a yield callback function. During streaming capture, the capture window can optionally issue notifications to your application of specific types of conditions. To install callback procedures for these notifications, use the following messages: - [**WM\_CAP\_SET\_CALLBACK\_ERROR**](wm-cap-set-callback-error.md) - [**WM\_CAP\_SET\_CALLBACK\_STATUS**](wm-cap-set-callback-status.md) - [**WM\_CAP\_SET\_CALLBACK\_YIELD**](wm-cap-set-callback-yield.md) - [**WM\_CAP\_SET\_CALLBACK\_VIDEOSTREAM**](wm-cap-set-callback-videostream.md) - [**WM\_CAP\_SET\_CALLBACK\_WAVESTREAM**](wm-cap-set-callback-wavestream.md) Read more on docs.microsoft.com. The WM\_CAP\_SEQUENCE\_NOFILE message initiates streaming video capture without writing data to a file. You can send this message explicitly or by using the capCaptureSequenceNoFile macro. Returns **TRUE** if successful or **FALSE** otherwise. This message is useful in conjunction with video stream or waveform-audio stream callback functions that let your application use the video and audio data directly. If you want to alter the parameters controlling streaming capture, use the [**WM\_CAP\_SET\_SEQUENCE\_SETUP**](wm-cap-set-sequence-setup.md) message prior to starting the capture. By default, the capture window does not allow other applications to continue running during capture. To override this, either set the **fYield** member of the [**CAPTUREPARMS**](/windows/win32/api/vfw/ns-vfw-captureparms) structure to **TRUE**, or install a yield callback function. During streaming capture, the capture window can optionally issue notifications to your application of specific types of conditions. To install callback procedures for these notifications, use the following messages: - [**WM\_CAP\_SET\_CALLBACK\_ERROR**](wm-cap-set-callback-error.md) - [**WM\_CAP\_SET\_CALLBACK\_STATUS**](wm-cap-set-callback-status.md) - [**WM\_CAP\_SET\_CALLBACK\_YIELD**](wm-cap-set-callback-yield.md) - [**WM\_CAP\_SET\_CALLBACK\_VIDEOSTREAM**](wm-cap-set-callback-videostream.md) - [**WM\_CAP\_SET\_CALLBACK\_WAVESTREAM**](wm-cap-set-callback-wavestream.md) Read more on docs.microsoft.com. The WM\_CAP\_SET\_SEQUENCE\_SETUP message sets the configuration parameters used with streaming capture. You can send this message explicitly or by using the capCaptureSetSetup macro. *wSize* Size, in bytes, of the structure referenced by**s**. *psCapParms* Pointer to a [**CAPTUREPARMS**](/windows/win32/api/vfw/ns-vfw-captureparms) structure. Returns **TRUE** if successful or **FALSE** otherwise. For information about the parameters used to control streaming capture, see the [**CAPTUREPARMS**](/windows/win32/api/vfw/ns-vfw-captureparms) structure. The WM\_CAP\_GET\_SEQUENCE\_SETUP message retrieves the current settings of the streaming capture parameters. You can send this message explicitly or by using the capCaptureGetSetup macro. *wSize* Size, in bytes, of the structure referenced by**s**. *s* Pointer to a [**CAPTUREPARMS**](/windows/win32/api/vfw/ns-vfw-captureparms) structure. Returns **TRUE** if successful or **FALSE** otherwise. For information about the parameters used to control streaming capture, see the [**CAPTUREPARMS**](/windows/win32/api/vfw/ns-vfw-captureparms) structure. The WM\_CAP\_SET\_MCI\_DEVICE message specifies the name of the MCI video device to be used to capture data. You can send this message explicitly or by using the capSetMCIDeviceName macro. *szName* Pointer to a null-terminated string containing the name of the device. Returns **TRUE** if successful or **FALSE** otherwise. This message stores the MCI device name in an internal structure. It does not open or access the device. The default device name is **NULL**. The WM\_CAP\_GET\_MCI\_DEVICE message retrieves the name of an MCI device previously set with the WM\_CAP\_SET\_MCI\_DEVICE message. You can send this message explicitly or by using the capGetMCIDeviceName macro. *wSize* Length, in bytes, of the buffer referenced by**szName**. *szName* Pointer to a null-terminated string that contains the MCI device name. Returns **TRUE** if successful or **FALSE** otherwise. Learn more about this API from docs.microsoft.com. The WM\_CAP\_STOP message stops the capture operation. You can send this message explicitly or by using the capCaptureStop macro. Returns **TRUE** if successful or **FALSE** otherwise. The capture operation must yield to use this message. Use the [**WM\_CAP\_ABORT**](wm-cap-abort.md) message to abandon the current capture operation. The WM\_CAP\_ABORT message stops the capture operation. Returns **TRUE** if successful or **FALSE** otherwise. The capture operation must yield to use this message. Use the [**WM\_CAP\_STOP**](wm-cap-stop.md) message to halt step capture at the current position, and then capture audio. Read more on docs.microsoft.com. The WM\_CAP\_SINGLE\_FRAME\_OPEN message opens the capture file for single-frame capturing. Any previous information in the capture file is overwritten. You can send this message explicitly or by using the capCaptureSingleFrameOpen macro. Returns **TRUE** if successful or **FALSE** otherwise. For information about installing callback functions, see the [**WM\_CAP\_SET\_CALLBACK\_ERROR**](wm-cap-set-callback-error.md) and [**WM\_CAP\_SET\_CALLBACK\_FRAME**](wm-cap-set-callback-frame.md) messages. The WM\_CAP\_SINGLE\_FRAME\_CLOSE message closes the capture file opened by the WM\_CAP\_SINGLE\_FRAME\_OPEN message. You can send this message explicitly or by using the capCaptureSingleFrameClose macro. Returns **TRUE** if successful or **FALSE** otherwise. For information about installing callback functions, see the [**WM\_CAP\_SET\_CALLBACK\_ERROR**](wm-cap-set-callback-error.md) and [**WM\_CAP\_SET\_CALLBACK\_FRAME**](wm-cap-set-callback-frame.md) messages. The WM\_CAP\_SINGLE\_FRAME message appends a single frame to a capture file that was opened using the WM\_CAP\_SINGLE\_FRAME\_OPEN message. You can send this message explicitly or by using the capCaptureSingleFrame macro. Returns **TRUE** if successful or **FALSE** otherwise. Learn more about this API from docs.microsoft.com. The WM\_CAP\_PAL\_OPEN message loads a new palette from a palette file and passes it to a capture driver. *szName* Pointer to a null-terminated string containing the palette filename. Returns **TRUE** if successful or **FALSE** otherwise. If an error occurs and an error callback function is set using the [**WM\_CAP\_SET\_CALLBACK\_ERROR**](wm-cap-set-callback-error.md) message, the error callback function is called. Learn more about this API from docs.microsoft.com. The WM\_CAP\_PAL\_SAVE message saves the current palette to a palette file. Palette files typically use the filename extension .PAL. You can send this message explicitly or by using the capPaletteSave macro. *szName* Pointer to a null-terminated string containing the palette filename. Returns **TRUE** if successful or **FALSE** otherwise. If an error occurs and an error callback function is set using the [**WM\_CAP\_SET\_CALLBACK\_ERROR**](wm-cap-set-callback-error.md) message, the error callback function is called. Learn more about this API from docs.microsoft.com. The WM\_CAP\_PAL\_PASTE message copies the palette from the clipboard and passes it to a capture driver. You can send this message explicitly or by using the capPalettePaste macro. Returns **TRUE** if successful or **FALSE** otherwise. If an error occurs and an error callback function is set using the [**WM\_CAP\_SET\_CALLBACK\_ERROR**](wm-cap-set-callback-error.md) message, the error callback function is called. A capture driver uses a palette when required by the specified digitized video format. The WM\_CAP\_PAL\_AUTOCREATE message requests that the capture driver sample video frames and automatically create a new palette. You can send this message explicitly or by using the capPaletteAuto macro. *iFrames* Number of frames to sample. *iColors* Number of colors in the palette. The maximum value for this parameter is 256. Returns **TRUE** if successful or **FALSE** otherwise. If an error occurs and an error callback function is set using the [**WM\_CAP\_SET\_CALLBACK\_ERROR**](wm-cap-set-callback-error.md) message, the error callback function is called. The sampled video sequence should include all the colors you want in the palette. To obtain the best palette, you might have to sample the whole sequence rather than a portion of it. The WM\_CAP\_PAL\_MANUALCREATE message requests that the capture driver manually sample video frames and create a new palette. You can send this message explicitly or by using the capPaletteManual macro. *fGrab* Palette histogram flag. Set this parameter to **TRUE** for each frame included in creating the optimal palette. After the last frame has been collected, set this parameter to **FALSE** to calculate the optimal palette and send it to the capture driver. *iColors* Number of colors in the palette. The maximum value for this parameter is 256. This value is used only during collection of the first frame in a sequence. Returns **TRUE** if successful or **FALSE** otherwise. If an error occurs and an error callback function is set using the [**WM\_CAP\_SET\_CALLBACK\_ERROR**](wm-cap-set-callback-error.md) message, the error callback function is called. Learn more about this API from docs.microsoft.com. The WM\_CAP\_SET\_CALLBACK\_CAPCONTROL message sets a callback function in the application giving it precise recording control. You can send this message explicitly or by using the capSetCallbackOnCapControl macro. *fpProc* Pointer to the callback function, of type [**capControlCallback**](/windows/desktop/api/Vfw/nc-vfw-capcontrolcallback). Specify **NULL** for this parameter to disable a previously installed callback function. Returns **TRUE** if successful or **FALSE** if a streaming capture or a single-frame capture session is in progress. A single callback function is used to give the application precise control over the moments that streaming capture begins and completes. The capture window first calls the procedure with *nState* set to CONTROLCALLBACK\_PREROLL after all buffers have been allocated and all other capture preparations have finished. This gives the application the ability to preroll video sources, returning from the callback function at the exact moment recording is to begin. A return value of **TRUE** from the callback function continues capture, and a return value of **FALSE** aborts capture. After capture begins, this callback function will be called frequently with *nState* set to CONTROLCALLBACK\_CAPTURING to allow the application to end capture by returning **FALSE**. An Active Directory property sheet extension calls the ADsPropGetInitInfo to obtain data about regarding the directory object that the property sheet extension applies to. This message has no return value. Learn more about this API from docs.microsoft.com. An Active Directory directory service property sheet extension calls the ADsPropSetHwnd to inform the notification object of the property page window handle. This message has no return value. An Active Directory property sheet extension normally calls the [**ADsPropSetHwnd**](/windows/desktop/api/Adsprop/nf-adsprop-adspropsethwnd) function while processing the [**WM\_INITDIALOG**](../dlgbox/wm-initdialog.md) message. The WM\_ADSPROP\_NOTIFY\_CHANGE message is used internally by the notification object. This message has no return value. Learn more about this API from docs.microsoft.com. An Active Directory directory service property sheet extension sends the WM\_ADSPROP\_NOTIFY\_APPLY message to the notification object if the property page PSN\_APPLY handler succeeds. This message has no return value. When adding pages to the Active Directory Manager MMC snap-in, Active Directory MMC property sheets create the notification objects by a call to the [**ADsPropCreateNotifyObj**](/windows/desktop/api/Adsprop/nf-adsprop-adspropcreatenotifyobj) function, and then passes the notification object handle to each property page. The WM\_ADSPROP\_NOTIFY\_SETFOCUS message is used internally by the notification object. This message has no return value. Learn more about this API from docs.microsoft.com. The WM\_ADSPROP\_NOTIFY\_FOREGROUND message is used internally by the notification object. This message has no return value. Learn more about this API from docs.microsoft.com. An Active Directory property sheet extension sends the WM\_ADSPROP\_NOTIFY\_EXIT message to the notification object when the notification object is no longer required. This message has no return value. The notification object will delete itself in response to this message. When this message has been sent, the notification object handle should be considered invalid. The WM\_ADSPROP\_NOTIFY\_ERROR message adds an error message to a list of error messages that are displayed by calling the ADsPropShowErrorDialog function. This message has no return value. The [**ADsPropSendErrorMessage**](/windows/desktop/api/Adsprop/nf-adsprop-adspropsenderrormessage) function is the preferred method of sending this message. The error messages added by the **WM\_ADSPROP\_NOTIFY\_ERROR** message are accumulated until [**ADsPropShowErrorDialog**](/windows/desktop/api/Adsprop/nf-adsprop-adspropshowerrordialog) is called. **ADsPropShowErrorDialog** combines and displays the accumulated error messages. When the error dialog is dismissed, the accumulated error messages are deleted. Read more on docs.microsoft.com. The operating system sends a WM\_RASDIALEVENT message to a window procedure when a change of state event occurs during a RAS connection process. If an application processes this message, it should return **TRUE**. Learn more about this API from docs.microsoft.com. The BitBlt function performs a bit-block transfer of the color data corresponding to a rectangle of pixels from the specified source device context into a destination device context. A handle to the destination device context. The x-coordinate, in logical units, of the upper-left corner of the destination rectangle. The y-coordinate, in logical units, of the upper-left corner of the destination rectangle. The width, in logical units, of the source and destination rectangles. The height, in logical units, of the source and the destination rectangles. A handle to the source device context. The x-coordinate, in logical units, of the upper-left corner of the source rectangle. The y-coordinate, in logical units, of the upper-left corner of the source rectangle. A raster-operation code. These codes define how the color data for the source rectangle is to be combined with the color data for the destination rectangle to achieve the final color. The following list shows some common raster operation codes. This doc was truncated. Read more on docs.microsoft.com. If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError. BitBlt only does clipping on the destination DC. If a rotation or shear transformation is in effect in the source device context, BitBlt returns an error. If other transformations exist in the source device context (and a matching transformation is not in effect in the destination device context), the rectangle in the destination device context is stretched, compressed, or rotated, as necessary. If the color formats of the source and destination device contexts do not match, the BitBlt function converts the source color format to match the destination format. When an enhanced metafile is being recorded, an error occurs if the source device context identifies an enhanced-metafile device context. Not all devices support the BitBlt function. For more information, see the RC_BITBLT raster capability entry in the GetDeviceCaps function as well as the following functions: MaskBlt, PlgBlt, and StretchBlt. BitBlt returns an error if the source and destination device contexts represent different devices. To transfer data between DCs for different devices, convert the memory bitmap to a DIB by calling GetDIBits. To display the DIB to the second device, call SetDIBits or StretchDIBits. ICM: No color management is performed when blits occur. Read more on docs.microsoft.com. The DeleteEnhMetaFile function deletes an enhanced-format metafile or an enhanced-format metafile handle. A handle to an enhanced metafile. If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. If the hemf parameter identifies an enhanced metafile stored in memory, the DeleteEnhMetaFile function deletes the metafile. If hemf identifies a metafile stored on a disk, the function deletes the metafile handle but does not destroy the actual metafile. An application can retrieve the file by calling the GetEnhMetaFile function. The CloseEnhMetaFile function closes an enhanced-metafile device context and returns a handle that identifies an enhanced-format metafile. Handle to an enhanced-metafile device context. If the function succeeds, the return value is a handle to an enhanced metafile. If the function fails, the return value is NULL. An application can use the enhanced-metafile handle returned by the CloseEnhMetaFile function to perform the following tasks: This doc was truncated. Read more on docs.microsoft.com. The DeleteObject function deletes a logical pen, brush, font, bitmap, region, or palette, freeing all system resources associated with the object. After the object is deleted, the specified handle is no longer valid. A handle to a logical pen, brush, font, bitmap, region, or palette. If the function succeeds, the return value is nonzero. If the specified handle is not valid or is currently selected into a DC, the return value is zero. Do not delete a drawing object (pen or brush) while it is still selected into a DC. When a pattern brush is deleted, the bitmap associated with the brush is not deleted. The bitmap must be deleted independently. Read more on docs.microsoft.com. The CombineRgn function combines two regions and stores the result in a third region. The two regions are combined according to the specified mode. A handle to a new region with dimensions defined by combining two other regions. (This region must exist before CombineRgn is called.) A handle to the first of two regions to be combined. A handle to the second of two regions to be combined. The return value specifies the type of the resulting region. It can be one of the following values. This doc was truncated. The three regions need not be distinct. For example, the hrgnSrc1 parameter can equal the hrgnDest parameter. The CreateBitmap function creates a bitmap with the specified width, height, and color format (color planes and bits-per-pixel). The bitmap width, in pixels. The bitmap height, in pixels. The number of color planes used by the device. The number of bits required to identify the color of a single pixel. A pointer to an array of color data used to set the colors in a rectangle of pixels. Each scan line in the rectangle must be word aligned (scan lines that are not word aligned must be padded with zeros). The buffer size expected, *cj*, can be calculated using the formula: This doc was truncated. Read more on docs.microsoft.com. If the function succeeds, the return value is a handle to a bitmap. If the function fails, the return value is NULL. This function can return the following value. This doc was truncated. The CreateBitmap function creates a device-dependent bitmap. After a bitmap is created, it can be selected into a device context by calling the SelectObject function. However, the bitmap can only be selected into a device context if the bitmap and the DC have the same format. The CreateBitmap function can be used to create color bitmaps. However, for performance reasons applications should use CreateBitmap to create monochrome bitmaps and CreateCompatibleBitmap to create color bitmaps. Whenever a color bitmap returned from CreateBitmap is selected into a device context, the system checks that the bitmap matches the format of the device context it is being selected into. Because CreateCompatibleBitmap takes a device context, it returns a bitmap that has the same format as the specified device context. Thus, subsequent calls to SelectObject are faster with a color bitmap from CreateCompatibleBitmap than with a color bitmap returned from CreateBitmap. If the bitmap is monochrome, zeros represent the foreground color and ones represent the background color for the destination device context. If an application sets the nWidth or nHeight parameters to zero, CreateBitmap returns the handle to a 1-by-1 pixel, monochrome bitmap. When you no longer need the bitmap, call the DeleteObject function to delete it. Read more on docs.microsoft.com. The CreateCompatibleBitmap function creates a bitmap compatible with the device that is associated with the specified device context. A handle to a device context. The bitmap width, in pixels. The bitmap height, in pixels. If the function succeeds, the return value is a handle to the compatible bitmap (DDB). If the function fails, the return value is NULL. The color format of the bitmap created by the CreateCompatibleBitmap function matches the color format of the device identified by the hdc parameter. This bitmap can be selected into any memory device context that is compatible with the original device. Because memory device contexts allow both color and monochrome bitmaps, the format of the bitmap returned by the CreateCompatibleBitmap function differs when the specified device context is a memory device context. However, a compatible bitmap that was created for a nonmemory device context always possesses the same color format and uses the same color palette as the specified device context. Note: When a memory device context is created, it initially has a 1-by-1 monochrome bitmap selected into it. If this memory device context is used in CreateCompatibleBitmap, the bitmap that is created is a monochrome bitmap. To create a color bitmap, use the HDC that was used to create the memory device context, as shown in the following code: This doc was truncated. Read more on docs.microsoft.com. The CreateCompatibleDC function creates a memory device context (DC) compatible with the specified device. A handle to an existing DC. If this handle is NULL, the function creates a memory DC compatible with the application's current screen. If the function succeeds, the return value is the handle to a memory DC. If the function fails, the return value is NULL. A memory DC exists only in memory. When the memory DC is created, its display surface is exactly one monochrome pixel wide and one monochrome pixel high. Before an application can use a memory DC for drawing operations, it must select a bitmap of the correct width and height into the DC. To select a bitmap into a DC, use the CreateCompatibleBitmap function, specifying the height, width, and color organization required. When a memory DC is created, all attributes are set to normal default values. The memory DC can be used as a normal DC. You can set the attributes; obtain the current settings of its attributes; and select pens, brushes, and regions. The CreateCompatibleDC function can only be used with devices that support raster operations. An application can determine whether a device supports these operations by calling the GetDeviceCaps function. When you no longer need the memory DC, call the DeleteDC function. We recommend that you call DeleteDC to delete the DC. However, you can also call DeleteObject with the HDC to delete the DC. If hdc is NULL, the thread that calls CreateCompatibleDC owns the HDC that is created. When this thread is destroyed, the HDC is no longer valid. Thus, if you create the HDC and pass it to another thread, then exit the first thread, the second thread will not be able to use the HDC. ICM: If the DC that is passed to this function is enabled for Image Color Management (ICM), the DC created by the function is ICM-enabled. The source and destination color spaces are specified in the DC. Read more on docs.microsoft.com. The CreateDC function creates a device context (DC) for a device using the specified name. (Unicode) A pointer to a null-terminated character string that specifies either DISPLAY or the name of a specific display device. For printing, we recommend that you pass NULL to lpszDriver because GDI ignores lpszDriver for printer devices. A pointer to a null-terminated character string that specifies the name of the specific output device being used, as shown by the Print Manager (for example, Epson FX-80). It is not the printer model name. The lpszDevice parameter must be used. To obtain valid names for displays, call EnumDisplayDevices. If lpszDriver is DISPLAY or the device name of a specific display device, then lpszDevice must be NULL or that same device name. If lpszDevice is NULL, then a DC is created for the primary display device. If there are multiple monitors on the system, calling CreateDC(TEXT("DISPLAY"),NULL,NULL,NULL) will create a DC covering all the monitors. Read more on docs.microsoft.com. This parameter is ignored and should be set to NULL. It is provided only for compatibility with 16-bit Windows. A pointer to a DEVMODE structure containing device-specific initialization data for the device driver. The DocumentProperties function retrieves this structure filled in for a specified device. The pdm parameter must be NULL if the device driver is to use the default initialization (if any) specified by the user. If lpszDriver is DISPLAY, pdm must be NULL; GDI then uses the display device's current DEVMODE. Read more on docs.microsoft.com. If the function succeeds, the return value is the handle to a DC for the specified device. If the function fails, the return value is NULL. Note that the handle to the DC can only be used by a single thread at any one time. For parameters lpszDriver and lpszDevice, call EnumDisplayDevices to obtain valid names for displays. When you no longer need the DC, call the DeleteDC function. If lpszDriver or lpszDevice is DISPLAY, the thread that calls CreateDC owns the HDC that is created. When this thread is destroyed, the HDC is no longer valid. Thus, if you create the HDC and pass it to another thread, then exit the first thread, the second thread will not be able to use the HDC. When you call CreateDC to create the HDC for a display device, you must pass to pdm either NULL or a pointer to DEVMODE that matches the current DEVMODE of the display device that lpszDevice specifies. We recommend to pass NULL and not to try to exactly match the DEVMODE for the current display device. When you call CreateDC to create the HDC for a printer device, the printer driver validates the DEVMODE. If the printer driver determines that the DEVMODE is invalid (that is, printer driver can’t convert or consume the DEVMODE), the printer driver provides a default DEVMODE to create the HDC for the printer device. ICM: To enable ICM, set the dmICMMethod member of the DEVMODE structure (pointed to by the pInitData parameter) to the appropriate value. Read more on docs.microsoft.com. The CreateDIBSection function creates a DIB that applications can write to directly. A handle to a device context. If the value of iUsage is DIB_PAL_COLORS, the function uses this device context's logical palette to initialize the DIB colors. A pointer to a BITMAPINFO structure that specifies various attributes of the DIB, including the bitmap dimensions and colors. The type of data contained in the bmiColors array member of the BITMAPINFO structure pointed to by pbmi (either logical palette indexes or literal RGB values). The following values are defined. This doc was truncated. Read more on docs.microsoft.com. A pointer to a variable that receives a pointer to the location of the DIB bit values. A handle to a file-mapping object that the function will use to create the DIB. This parameter can be NULL. If hSection is not NULL, it must be a handle to a file-mapping object created by calling the CreateFileMapping function with the PAGE_READWRITE or PAGE_WRITECOPY flag. Read-only DIB sections are not supported. Handles created by other means will cause CreateDIBSection to fail. If hSection is not NULL, the CreateDIBSection function locates the bitmap bit values at offset dwOffset in the file-mapping object referred to by hSection. An application can later retrieve the hSection handle by calling the GetObject function with the HBITMAP returned by CreateDIBSection. If hSection is NULL, the system allocates memory for the DIB. In this case, the CreateDIBSection function ignores the dwOffset parameter. An application cannot later obtain a handle to this memory. The dshSection member of the DIBSECTION structure filled in by calling the GetObject function will be NULL. Read more on docs.microsoft.com. The offset from the beginning of the file-mapping object referenced by hSection where storage for the bitmap bit values is to begin. This value is ignored if hSection is NULL. The bitmap bit values are aligned on doubleword boundaries, so dwOffset must be a multiple of the size of a DWORD. If the function succeeds, the return value is a handle to the newly created DIB, and *ppvBits points to the bitmap bit values. If the function fails, the return value is NULL, and *ppvBits is NULL. To get extended error information, call GetLastError. GetLastError can return the following value: This doc was truncated. As noted above, if hSection is NULL, the system allocates memory for the DIB. The system closes the handle to that memory when you later delete the DIB by calling the DeleteObject function. If hSection is not NULL, you must close the hSection memory handle yourself after calling DeleteObject to delete the bitmap. You cannot paste a DIB section from one application into another application. CreateDIBSection does not use the BITMAPINFOHEADER parameters biXPelsPerMeter or biYPelsPerMeter and will not provide resolution information in the BITMAPINFO structure. You need to guarantee that the GDI subsystem has completed any drawing to a bitmap created by CreateDIBSection before you draw to the bitmap yourself. Access to the bitmap must be synchronized. Do this by calling the GdiFlush function. This applies to any use of the pointer to the bitmap bit values, including passing the pointer in calls to functions such as SetDIBits. ICM: No color management is done. Read more on docs.microsoft.com. The CreateEnhMetaFile function creates a device context for an enhanced-format metafile. This device context can be used to store a device-independent picture. (Unicode) A handle to a reference device for the enhanced metafile. This parameter can be NULL; for more information, see Remarks. A pointer to the file name for the enhanced metafile to be created. If this parameter is NULL, the enhanced metafile is memory based and its contents are lost when it is deleted by using the DeleteEnhMetaFile function. A pointer to a RECT structure that specifies the dimensions (in .01-millimeter units) of the picture to be stored in the enhanced metafile. A pointer to a string that specifies the name of the application that created the picture, as well as the picture's title. This parameter can be NULL; for more information, see Remarks. If the function succeeds, the return value is a handle to the device context for the enhanced metafile. If the function fails, the return value is NULL. Where text arguments must use Unicode characters, use the CreateEnhMetaFile function as a wide-character function. Where text arguments must use characters from the Windows character set, use this function as an ANSI function. The system uses the reference device identified by the hdcRef parameter to record the resolution and units of the device on which a picture originally appeared. If the hdcRef parameter is NULL, it uses the current display device for reference. The left and top members of the RECT structure pointed to by the lpRect parameter must be less than the right and bottom members, respectively. Points along the edges of the rectangle are included in the picture. If lpRect is NULL, the graphics device interface (GDI) computes the dimensions of the smallest rectangle that surrounds the picture drawn by the application. The lpRect parameter should be provided where possible. The string pointed to by the lpDescription parameter must contain a null character between the application name and the picture name and must terminate with two null characters, for example, "XYZ Graphics Editor\0Bald Eagle\0\0", where \0 represents the null character. If lpDescription is NULL, there is no corresponding entry in the enhanced-metafile header. Applications use the device context created by this function to store a graphics picture in an enhanced metafile. The handle identifying this device context can be passed to any GDI function. After an application stores a picture in an enhanced metafile, it can display the picture on any output device by calling the PlayEnhMetaFile function. When displaying the picture, the system uses the rectangle pointed to by the lpRect parameter and the resolution data from the reference device to position and scale the picture. The device context returned by this function contains the same default attributes associated with any new device context. Applications must use the GetWinMetaFileBits function to convert an enhanced metafile to the older Windows metafile format. The file name for the enhanced metafile should use the .emf extension. Read more on docs.microsoft.com. The CreateFontIndirect function creates a logical font that has the specified characteristics. The font can subsequently be selected as the current font for any device context. (Unicode) A pointer to a LOGFONT structure that defines the characteristics of the logical font. If the function succeeds, the return value is a handle to a logical font. If the function fails, the return value is NULL. The CreateFontIndirect function creates a logical font with the characteristics specified in the LOGFONT structure. When this font is selected by using the SelectObject function, GDI's font mapper attempts to match the logical font with an existing physical font. If it fails to find an exact match, it provides an alternative whose characteristics match as many of the requested characteristics as possible. To get the appropriate font on different language versions of the OS, call EnumFontFamiliesEx with the desired font characteristics in the LOGFONT structure, retrieve the appropriate typeface name, and create the font using CreateFont or CreateFontIndirect. When you no longer need the font, call the DeleteObject function to delete it. The fonts for many East Asian languages have two typeface names: an English name and a localized name. CreateFont and CreateFontIndirect take the localized typeface name only on a system locale that matches the language, while they take the English typeface name on all other system locales. The best method is to try one name and, on failure, try the other. Note that EnumFonts, EnumFontFamilies, and EnumFontFamiliesEx return the English typeface name if the system locale does not match the language of the font. The font mapper for CreateFont, CreateFontIndirect, and CreateFontIndirectEx recognizes both the English and the localized typeface name, regardless of locale. Read more on docs.microsoft.com. The CreateIC function creates an information context for the specified device. (Unicode) A pointer to a null-terminated character string that specifies the name of the device driver (for example, Epson). A pointer to a null-terminated character string that specifies the name of the specific output device being used, as shown by the Print Manager (for example, Epson FX-80). It is not the printer model name. The lpszDevice parameter must be used. This parameter is ignored and should be set to NULL. It is provided only for compatibility with 16-bit Windows. A pointer to a DEVMODE structure containing device-specific initialization data for the device driver. The DocumentProperties function retrieves this structure filled in for a specified device. The lpdvmInit parameter must be NULL if the device driver is to use the default initialization (if any) specified by the user. If the function succeeds, the return value is the handle to an information context. If the function fails, the return value is NULL. When you no longer need the information DC, call the DeleteDC function. > [!NOTE] > The wingdi.h header defines CreateIC as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see [Conventions for Function Prototypes](/windows/win32/intl/conventions-for-function-prototypes). Read more on docs.microsoft.com. The CreatePen function creates a logical pen that has the specified style, width, and color. The pen can subsequently be selected into a device context and used to draw lines and curves. The width of the pen, in logical units. If nWidth is zero, the pen is a single pixel wide, regardless of the current transformation. CreatePen returns a pen with the specified width but with the PS_SOLID style if you specify a width greater than one for the following styles: PS_DASH, PS_DOT, PS_DASHDOT, PS_DASHDOTDOT. Read more on docs.microsoft.com. A color reference for the pen color. To generate a COLORREF structure, use the RGB macro. If the function succeeds, the return value is a handle that identifies a logical pen. If the function fails, the return value is NULL. After an application creates a logical pen, it can select that pen into a device context by calling the SelectObject function. After a pen is selected into a device context, it can be used to draw lines and curves. If the value specified by the nWidth parameter is zero, a line drawn with the created pen always is a single pixel wide regardless of the current transformation. If the value specified by nWidth is greater than 1, the fnPenStyle parameter must be PS_NULL, PS_SOLID, or PS_INSIDEFRAME. If the value specified by nWidth is greater than 1 and fnPenStyle is PS_INSIDEFRAME, the line associated with the pen is drawn inside the frame of all primitives except polygons and polylines. If the value specified by nWidth is greater than 1, fnPenStyle is PS_INSIDEFRAME, and the color specified by the crColor parameter does not match one of the entries in the logical palette, the system draws lines by using a dithered color. Dithered colors are not available with solid pens. When using an iStyle parameter of PS_DASH, PS_DOT, PS_DASHDOT or PS_DASHDOTDOT, in order to make the gaps between the dashes or dots transparent, use SetBkMode to set the mode to TRANSPARENT. When you no longer need the pen, call the DeleteObject function to delete it. ICM: No color management is done at creation. However, color management is performed when the pen is selected into an ICM-enabled device context. Read more on docs.microsoft.com. The CreateRectRgn function creates a rectangular region. Specifies the x-coordinate of the upper-left corner of the region in logical units. Specifies the y-coordinate of the upper-left corner of the region in logical units. Specifies the x-coordinate of the lower-right corner of the region in logical units. Specifies the y-coordinate of the lower-right corner of the region in logical units. If the function succeeds, the return value is the handle to the region. If the function fails, the return value is NULL. When you no longer need the HRGN object, call the DeleteObject function to delete it. Region coordinates are represented as 27-bit signed integers. Regions created by the Create<shape>Rgn methods (such as CreateRectRgn and CreatePolygonRgn) only include the interior of the shape; the shape's outline is excluded from the region. This means that any point on a line between two sequential vertices is not included in the region. If you were to call PtInRegion for such a point, it would return zero as the result. Read more on docs.microsoft.com. The DeleteDC function deletes the specified device context (DC). 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 must not delete a DC whose handle was obtained by calling the GetDC function. Instead, it must call the ReleaseDC function to free the DC. The EnumEnhMetaFile function enumerates the records within an enhanced-format metafile by retrieving each record and passing it to the specified callback function. A handle to a device context. This handle is passed to the callback function. A handle to an enhanced metafile. A pointer to the application-supplied callback function. For more information, see the EnhMetaFileProc function. A pointer to a RECT structure that specifies the coordinates, in logical units, of the picture's upper-left and lower-right corners. If the callback function successfully enumerates all the records in the enhanced metafile, the return value is nonzero. If the callback function does not successfully enumerate all the records in the enhanced metafile, the return value is zero. Points along the edge of the rectangle pointed to by the lpRect parameter are included in the picture. If the hdc parameter is NULL, the system ignores lpRect. If the callback function calls the PlayEnhMetaFileRecord function, hdc must identify a valid device context. The system uses the device context's transformation and mapping mode to transform the picture displayed by the PlayEnhMetaFileRecord function. You can use the EnumEnhMetaFile function to embed one enhanced-metafile within another. Read more on docs.microsoft.com. The GetClipRgn function retrieves a handle identifying the current application-defined clipping region for the specified device context. A handle to the device context. A handle to an existing region before the function is called. After the function returns, this parameter is a handle to a copy of the current clipping region. If the function succeeds and there is no clipping region for the given device context, the return value is zero. If the function succeeds and there is a clipping region for the given device context, the return value is 1. If an error occurs, the return value is -1. An application-defined clipping region is a clipping region identified by the SelectClipRgn function. It is not a clipping region created when the application calls the BeginPaint function. If the function succeeds, the hrgn parameter is a handle to a copy of the current clipping region. Subsequent changes to this copy will not affect the current clipping region. Read more on docs.microsoft.com. The GetDeviceCaps function retrieves device-specific information for the specified device. A handle to the DC. The return value specifies the value of the desired item. When nIndex is BITSPIXEL and the device has 15bpp or 16bpp, the return value is 16. When nIndex is SHADEBLENDCAPS: This doc was truncated. Read more on docs.microsoft.com. The GetEnhMetaFileBits function retrieves the contents of the specified enhanced-format metafile and copies them into a buffer. A handle to the enhanced metafile. The size, in bytes, of the buffer to receive the data. A pointer to a buffer that receives the metafile data. The buffer must be sufficiently large to contain the data. If lpbBuffer is NULL, the function returns the size necessary to hold the data. If the function succeeds and the buffer pointer is NULL, the return value is the size of the enhanced metafile, in bytes. If the function succeeds and the buffer pointer is a valid pointer, the return value is the number of bytes copied to the buffer. If the function fails, the return value is zero. After the enhanced-metafile bits are retrieved, they can be used to create a memory-based metafile by calling the SetEnhMetaFileBits function. The GetEnhMetaFileBits function does not invalidate the enhanced-metafile handle. The application must call the DeleteEnhMetaFile function to delete the handle when it is no longer needed. The metafile contents retrieved by this function are in the enhanced format. To retrieve the metafile contents in the Windows format, use the GetWinMetaFileBits function. Read more on docs.microsoft.com. The GetObjectW (Unicode) function (wingdi.h) retrieves information for the specified graphics object. If the function succeeds, and lpvObject is a valid pointer, the return value is the number of bytes stored into the buffer. If the function succeeds, and lpvObject is NULL, the return value is the number of bytes required to hold the information the function would store into the buffer. If the function fails, the return value is zero. The buffer pointed to by the lpvObject parameter must be sufficiently large to receive the information about the graphics object. Depending on the graphics object, the function uses a BITMAP, DIBSECTION, EXTLOGPEN, LOGBRUSH, LOGFONT, or LOGPEN structure, or a count of table entries (for a logical palette). If hgdiobj is a handle to a bitmap created by calling CreateDIBSection, and the specified buffer is large enough, the GetObject function returns a DIBSECTION structure. In addition, the bmBits member of the BITMAP structure contained within the DIBSECTION will contain a pointer to the bitmap's bit values. If hgdiobj is a handle to a bitmap created by any other means, GetObject returns only the width, height, and color format information of the bitmap. You can obtain the bitmap's bit values by calling the GetDIBits or GetBitmapBits function. If hgdiobj is a handle to a logical palette, GetObject retrieves a 2-byte integer that specifies the number of entries in the palette. The function does not retrieve the LOGPALETTE structure defining the palette. To retrieve information about palette entries, an application can call the GetPaletteEntries function. If hgdiobj is a handle to a font, the LOGFONT that is returned is the LOGFONT used to create the font. If Windows had to make some interpolation of the font because the precise LOGFONT could not be represented, the interpolation will not be reflected in the LOGFONT. For example, if you ask for a vertical version of a font that doesn't support vertical painting, the LOGFONT indicates the font is vertical, but Windows will paint it horizontally. Read more on docs.microsoft.com. The GetObjectType retrieves the type of the specified object. A handle to the graphics object. If the function succeeds, the return value identifies the object. This value can be one of the following. This doc was truncated. Learn more about this API from docs.microsoft.com. 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. Read more on docs.microsoft.com. The GetRegionData function fills the specified buffer with data describing a region. This data includes the dimensions of the rectangles that make up the region. A handle to the region. The size, in bytes, of the lpRgnData buffer. A pointer to a RGNDATA structure that receives the information. The dimensions of the region are in logical units. If this parameter is NULL, the return value contains the number of bytes needed for the region data. If the function succeeds and dwCount specifies an adequate number of bytes, the return value is always dwCount. If dwCount is too small or the function fails, the return value is 0. If lpRgnData is NULL, the return value is the required number of bytes. If the function fails, the return value is zero. The GetRegionData function is used in conjunction with the ExtCreateRegion function. The GetStockObject function retrieves a handle to one of the stock pens, brushes, fonts, or palettes. If the function succeeds, the return value is a handle to the requested logical object. If the function fails, the return value is NULL. It is not recommended that you employ this method to obtain the current font used by dialogs and windows. Instead, use the SystemParametersInfo function with the SPI_GETNONCLIENTMETRICS parameter to retrieve the current font. SystemParametersInfo will take into account the current theme and provides font information for captions, menus, and message dialogs. Use the DKGRAY_BRUSH, GRAY_BRUSH, and LTGRAY_BRUSH stock objects only in windows with the CS_HREDRAW and CS_VREDRAW styles. Using a gray stock brush in any other style of window can lead to misalignment of brush patterns after a window is moved or sized. The origins of stock brushes cannot be adjusted. The HOLLOW_BRUSH and NULL_BRUSH stock objects are equivalent. It is not necessary (but it is not harmful) to delete stock objects by calling DeleteObject. Both DC_BRUSH and DC_PEN can be used interchangeably with other stock objects like BLACK_BRUSH and BLACK_PEN. For information on retrieving the current pen or brush color, see GetDCBrushColor and GetDCPenColor. See Setting the Pen or Brush Color for an example of setting colors. The GetStockObject function with an argument of DC_BRUSH or DC_PEN can be used interchangeably with the SetDCPenColor and SetDCBrushColor functions. Read more on docs.microsoft.com. The GetViewportExtEx function retrieves the x-extent and y-extent of the current viewport for the specified device context. A handle to the device context. A pointer to a SIZE structure that receives the x- and y-extents, in device units. If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. Learn more about this API from docs.microsoft.com. The GetViewportOrgEx function retrieves the x-coordinates and y-coordinates of the viewport origin for the specified device context. A handle to the device context. A pointer to a POINT structure that receives the coordinates of the origin, in device units. If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. Learn more about this API from docs.microsoft.com. The GetWindowOrgEx function retrieves the x-coordinates and y-coordinates of the window origin for the specified device context. A handle to the device context. A pointer to a POINT structure that receives the coordinates, in logical units, of the window origin. If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. Learn more about this API from docs.microsoft.com. The GetWorldTransform function retrieves the current world-space to page-space transformation. A handle to the device context. A pointer to an XFORM structure that receives the current world-space to page-space transformation. If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. The precision of the transformation may be altered if an application calls the ModifyWorldTransform function prior to calling GetWorldTransform. (This is because the internal format for storing transformation values uses a higher precision than a FLOAT value.) The IntersectClipRect function creates a new clipping region from the intersection of the current clipping region and the specified rectangle. A handle to the device context. The x-coordinate, in logical units, of the upper-left corner of the rectangle. The y-coordinate, in logical units, of the upper-left corner of the rectangle. The x-coordinate, in logical units, of the lower-right corner of the rectangle. The y-coordinate, in logical units, of the lower-right corner of the rectangle. The return value specifies the new clipping region's type and can be one of the following values. This doc was truncated. The lower and right-most edges of the given rectangle are excluded from the clipping region. If a clipping region does not already exist then the system may apply a default clipping region to the specified HDC. A clipping region is then created from the intersection of that default clipping region and the rectangle specified in the function parameters. Read more on docs.microsoft.com. The OffsetViewportOrgEx function modifies the viewport origin for a device context using the specified horizontal and vertical offsets. A handle to the device context. The horizontal offset, in device units. The vertical offset, in device units. A pointer to a POINT structure. The previous viewport origin, in device units, is placed in this structure. If lpPoint is NULL, the previous viewport origin is not returned. If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. The new origin is the sum of the current origin and the horizontal and vertical offsets. The DeleteMetaFile function deletes a Windows-format metafile or Windows-format metafile handle. A handle to a Windows-format metafile. If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. If the metafile identified by the hmf parameter is stored in memory (rather than on a disk), its content is lost when it is deleted by using the DeleteMetaFile function. 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. Read more on docs.microsoft.com. The Rectangle function draws a rectangle. The rectangle is outlined by using the current pen and filled by using the current brush. A handle to the device context. The x-coordinate, in logical coordinates, of the upper-left corner of the rectangle. The y-coordinate, in logical coordinates, of the upper-left corner of the rectangle. The x-coordinate, in logical coordinates, of the lower-right corner of the rectangle. The y-coordinate, in logical coordinates, of the lower-right corner of the rectangle. If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. The current position is neither used nor updated by Rectangle. The rectangle that is drawn excludes the bottom and right edges. If a PS_NULL pen is used, the dimensions of the rectangle are 1 pixel less in height and 1 pixel less in width. Read more on docs.microsoft.com. The RestoreDC function restores a device context (DC) to the specified state. The DC is restored by popping state information off a stack created by earlier calls to the SaveDC function. A handle to the DC. The saved state to be restored. If this parameter is positive, nSavedDC represents a specific instance of the state to be restored. If this parameter is negative, nSavedDC represents an instance relative to the current state. For example, -1 restores the most recently saved state. If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. Each DC maintains a stack of saved states. The SaveDC function pushes the current state of the DC onto its stack of saved states. That state can be restored only to the same DC from which it was created. After a state is restored, the saved state is destroyed and cannot be reused. Furthermore, any states saved after the restored state was created are also destroyed and cannot be used. In other words, the RestoreDC function pops the restored state (and any subsequent states) from the state information stack. The SaveDC function saves the current state of the specified device context (DC) by copying data describing selected objects and graphic modes (such as the bitmap, brush, palette, font, pen, region, drawing mode, and mapping mode) to a context stack. A handle to the DC whose state is to be saved. If the function succeeds, the return value identifies the saved state. If the function fails, the return value is zero. The SaveDC function can be used any number of times to save any number of instances of the DC state. A saved state can be restored by using the RestoreDC function. Read more on docs.microsoft.com. The SelectClipRgn function selects a region as the current clipping region for the specified device context. A handle to the device context. A handle to the region to be selected. The return value specifies the region's complexity and can be one of the following values. This doc was truncated. Only a copy of the selected region is used. The region itself can be selected for any number of other device contexts or it can be deleted. The SelectClipRgn function assumes that the coordinates for a region are specified in device units. To remove a device-context's clipping region, specify a NULL region handle. Read more on docs.microsoft.com. The SelectObject function selects an object into the specified device context (DC). The new object replaces the previous object of the same type. A handle to the DC. A handle to the object to be selected. The specified object must have been created by using one of the following functions. This doc was truncated. Read more on docs.microsoft.com. If the selected object is not a region and the function succeeds, the return value is a handle to the object being replaced. If the selected object is a region and the function succeeds, the return value is one of the following values. This doc was truncated. This function returns the previously selected object of the specified type. An application should always replace a new object with the original, default object after it has finished drawing with the new object. An application cannot select a single bitmap into more than one DC at a time. ICM: If the object being selected is a brush or a pen, color management is performed. Read more on docs.microsoft.com. 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.) Read more on docs.microsoft.com. 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. Read more on docs.microsoft.com. The SetBkColor function sets the current background color to the specified color value, or to the nearest physical color if the device cannot represent the specified color value. A handle to the device context. The new background color. To make a COLORREF value, use the RGB macro. If the function succeeds, the return value specifies the previous background color as a COLORREF value. If the function fails, the return value is CLR_INVALID. This function fills the gaps between styled lines drawn using a pen created by the CreatePen function; it does not fill the gaps between styled lines drawn using a pen created by the ExtCreatePen function. The SetBkColor function also sets the background colors for TextOut and ExtTextOut. If the background mode is OPAQUE, the background color is used to fill gaps between styled lines, gaps between hatched lines in brushes, and character cells. The background color is also used when converting bitmaps from color to monochrome and vice versa. Read more on docs.microsoft.com. The SetBkMode function sets the background mix mode of the specified device context. The background mix mode is used with text, hatched brushes, and pen styles that are not solid lines. A handle to the device context. If the function succeeds, the return value specifies the previous background mode. If the function fails, the return value is zero. The SetBkMode function affects the line styles for lines drawn using a pen created by the CreatePen function. SetBkMode does not affect lines drawn using a pen created by the ExtCreatePen function. The SetMapMode function sets the mapping mode of the specified device context. The mapping mode defines the unit of measure used to transform page-space units into device-space units, and also defines the orientation of the device's x and y axes. A handle to the device context. If the function succeeds, the return value identifies the previous mapping mode. If the function fails, the return value is zero. The MM_TEXT mode allows applications to work in device pixels, whose size varies from device to device. The MM_HIENGLISH, MM_HIMETRIC, MM_LOENGLISH, MM_LOMETRIC, and MM_TWIPS modes are useful for applications drawing in physically meaningful units (such as inches or millimeters). The MM_ISOTROPIC mode ensures a 1:1 aspect ratio. The MM_ANISOTROPIC mode allows the x-coordinates and y-coordinates to be adjusted independently. Read more on docs.microsoft.com. The SetROP2 function sets the current foreground mix mode. A handle to the device context. If the function succeeds, the return value specifies the previous mix mode. If the function fails, the return value is zero. Mix modes define how GDI combines source and destination colors when drawing with the current pen. The mix modes are binary raster operation codes, representing all possible Boolean functions of two variables, using the binary operations AND, OR, and XOR (exclusive OR), and the unary operation NOT. The mix mode is for raster devices only; it is not available for vector devices. The SetTextAlign function sets the text-alignment flags for the specified device context. A handle to the device context. The text alignment by using a mask of the values in the following list. Only one flag can be chosen from those that affect horizontal and vertical alignment. In addition, only one of the two flags that alter the current position can be chosen. This doc was truncated. Read more on docs.microsoft.com. If the function succeeds, the return value is the previous text-alignment setting. If the function fails, the return value is GDI_ERROR. The TextOut and ExtTextOut functions use the text-alignment flags to position a string of text on a display or other device. The flags specify the relationship between a reference point and a rectangle that bounds the text. The reference point is either the current position or a point passed to a text output function. The rectangle that bounds the text is formed by the character cells in the text string. The best way to get left-aligned text is to use either This doc was truncated. Read more on docs.microsoft.com. The SetTextColor function sets the text color for the specified device context to the specified color. A handle to the device context. The color of the text. If the function succeeds, the return value is a color reference for the previous text color as a COLORREF value. If the function fails, the return value is CLR_INVALID. The text color is used to draw the face of each character written by the TextOut and ExtTextOut functions. The text color is also used in converting bitmaps from color to monochrome and vice versa. Closes an open object handle. A valid handle to an open object. If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError. If the application is running under a debugger, the function will throw an exception if it receives either a handle value that is not valid or a pseudo-handle value. This can happen if you close a handle twice, or if you call CloseHandle on a handle returned by the FindFirstFile function instead of calling the FindClose function. The CloseHandle function closes handles to the following objects: This doc was truncated. Read more on docs.microsoft.com. Frees the specified global memory object and invalidates its handle. A handle to the global memory object. This handle is returned by either the GlobalAlloc or GlobalReAlloc function. It is not safe to free memory allocated with LocalAlloc. Read more on docs.microsoft.com. If the function succeeds, the return value is NULL. If the function fails, the return value is equal to a handle to the global memory object. To get extended error information, call GetLastError. If the process examines or modifies the memory after it has been freed, heap corruption may occur or an access violation exception (EXCEPTION_ACCESS_VIOLATION) may be generated. The GlobalFree function will free a locked memory object. A locked memory object has a lock count greater than zero. The GlobalLock function locks a global memory object and increments the lock count by one. The GlobalUnlock function unlocks it and decrements the lock count by one. To get the lock count of a global memory object, use the GlobalFlags function. If an application is running under a debug version of the system, GlobalFree will issue a message that tells you that a locked object is being freed. If you are debugging the application, GlobalFree will enter a breakpoint just before freeing a locked object. This allows you to verify the intended behavior, then continue execution. Read more on docs.microsoft.com. Retrieves the thread identifier of the calling thread. The return value is the thread identifier of the calling thread. Until the thread terminates, the thread identifier uniquely identifies the thread throughout the system. Returns the locale identifier for the system locale.Note  Any application that runs only on Windows Vista and later should use GetSystemDefaultLocaleName in preference to this function. Returns the locale identifier for the system default locale, identified by LOCALE_SYSTEM_DEFAULT. This function can retrieve data from custom locales. Data is not guaranteed to be the same from computer to computer or between runs of an application. If your application must persist or transmit data, see Using Persistent Locale Data. Returns the locale identifier of the current locale for the calling thread.Note  This function can retrieve data that changes between releases, for example, due to a custom locale. Returns the locale identifier of the locale associated with the current thread. Windows Vista: This function can return the identifier of a custom locale. If the current thread locale is a custom locale, the function returns LOCALE_CUSTOM_DEFAULT. If the current thread locale is a supplemental custom locale, the function can return LOCALE_CUSTOM_UNSPECIFIED. All supplemental locales share this locale identifier. When an application process launches, it uses the Standards and Formats variable for the locale. For more information, see NLS Terminology. When a new thread is created in a process, it inherits the locale of the creating thread. This locale can be either the default Standards and Formats locale or a different locale set for the creating thread in a call to SetThreadLocale. GetThreadLocale and SetThreadLocale can be used to modify the locale of the new thread. Read more on docs.microsoft.com. Allocates the specified number of bytes from the heap. (GlobalAlloc) The number of bytes to allocate. If this parameter is zero and the uFlags parameter specifies GMEM_MOVEABLE, the function returns a handle to a memory object that is marked as discarded. If the function succeeds, the return value is a handle to the newly allocated memory object. If the function fails, the return value is NULL. To get extended error information, call GetLastError. Windows memory management does not provide a separate local heap and global heap. Therefore, the GlobalAlloc and LocalAlloc functions are essentially the same. The movable-memory flags GHND and GMEM_MOVABLE add unnecessary overhead and require locking to be used safely. They should be avoided unless documentation specifically states that they should be used. New applications should use the heap functions to allocate and manage memory unless the documentation specifically states that a global function should be used. For example, the global functions are still used with Dynamic Data Exchange (DDE), the clipboard functions, and OLE data objects. If the GlobalAlloc function succeeds, it allocates at least the amount of memory requested. If the actual amount allocated is greater than the amount requested, the process can use the entire amount. To determine the actual number of bytes allocated, use the GlobalSize function. If the heap does not contain sufficient free space to satisfy the request, GlobalAlloc returns NULL. Because NULL is used to indicate an error, virtual address zero is never allocated. It is, therefore, easy to detect the use of a NULL pointer. Memory allocated with this function is guaranteed to be aligned on an 8-byte boundary. To execute dynamically generated code, use the VirtualAlloc function to allocate memory and the VirtualProtect function to grant PAGE_EXECUTE access. To free the memory, use the GlobalFree function. It is not safe to free memory allocated with GlobalAlloc using LocalFree. Read more on docs.microsoft.com. Locks a global memory object and returns a pointer to the first byte of the object's memory block. A handle to the global memory object. This handle is returned by either the GlobalAlloc or GlobalReAlloc function. Read more on docs.microsoft.com. If the function succeeds, the return value is a pointer to the first byte of the memory block. If the function fails, the return value is NULL. To get extended error information, call GetLastError. The internal data structures for each memory object include a lock count that is initially zero. For movable memory objects, GlobalLock increments the count by one, and the GlobalUnlock function decrements the count by one. Each successful call that a process makes to GlobalLock for an object must be matched by a corresponding call to GlobalUnlock. Locked memory will not be moved or discarded, unless the memory object is reallocated by using the GlobalReAlloc function. The memory block of a locked memory object remains locked until its lock count is decremented to zero, at which time it can be moved or discarded. Memory objects allocated with GMEM_FIXED always have a lock count of zero. For these objects, the value of the returned pointer is equal to the value of the specified handle. If the specified memory block has been discarded or if the memory block has a zero-byte size, this function returns NULL. Discarded objects always have a lock count of zero. Read more on docs.microsoft.com. Changes the size or attributes of a specified global memory object. The size can increase or decrease. A handle to the global memory object to be reallocated. This handle is returned by either the GlobalAlloc or GlobalReAlloc function. Read more on docs.microsoft.com. The new size of the memory block, in bytes. If uFlags specifies GMEM_MODIFY, this parameter is ignored. The reallocation options. If GMEM_MODIFY is specified, the function modifies the attributes of the memory object only (the dwBytes parameter is ignored.) Otherwise, the function reallocates the memory object. You can optionally combine GMEM_MODIFY with the following value. This doc was truncated. Read more on docs.microsoft.com. If the function succeeds, the return value is a handle to the reallocated memory object. If the function fails, the return value is NULL. To get extended error information, call GetLastError. If GlobalReAlloc reallocates a movable object, the return value is a handle to the memory object. To convert the handle to a pointer, use the GlobalLock function. If GlobalReAlloc reallocates a fixed object, the value of the handle returned is the address of the first byte of the memory block. To access the memory, a process can simply cast the return value to a pointer. If GlobalReAlloc fails, the original memory is not freed, and the original handle and pointer are still valid. Read more on docs.microsoft.com. Retrieves the current size of the specified global memory object, in bytes. A handle to the global memory object. This handle is returned by either the GlobalAlloc or GlobalReAlloc function. Read more on docs.microsoft.com. If the function succeeds, the return value is the size of the specified global memory object, in bytes. If the specified handle is not valid or if the object has been discarded, the return value is zero. To get extended error information, call GetLastError. The size of a memory block may be larger than the size requested when the memory was allocated. To verify that the specified object's memory block has not been discarded, use the GlobalFlags function before calling GlobalSize. Read more on docs.microsoft.com. Decrements the lock count associated with a memory object that was allocated with GMEM_MOVEABLE. A handle to the global memory object. This handle is returned by either the GlobalAlloc or GlobalReAlloc function. Read more on docs.microsoft.com. If the memory object is still locked after decrementing the lock count, the return value is a nonzero value. If the memory object is unlocked after decrementing the lock count, the function returns zero and GetLastError returns NO_ERROR. If the function fails, the return value is zero and GetLastError returns a value other than NO_ERROR. The internal data structures for each memory object include a lock count that is initially zero. For movable memory objects, the GlobalLock function increments the count by one, and GlobalUnlock decrements the count by one. For each call that a process makes to GlobalLock for an object, it must eventually call GlobalUnlock. Locked memory will not be moved or discarded, unless the memory object is reallocated by using the GlobalReAlloc function. The memory block of a locked memory object remains locked until its lock count is decremented to zero, at which time it can be moved or discarded. Memory objects allocated with GMEM_FIXED always have a lock count of zero. If the specified memory block is fixed memory, this function returns TRUE. If the memory object is already unlocked, GlobalUnlock returns FALSE and GetLastError reports ERROR_NOT_LOCKED. A process should not rely on the return value to determine the number of times it must subsequently call GlobalUnlock for a memory object. Read more on docs.microsoft.com. Frees the loaded dynamic-link library (DLL) module and, if necessary, decrements its reference count. A handle to the loaded library module. The LoadLibrary, LoadLibraryEx, GetModuleHandle, or GetModuleHandleEx function returns this handle. Read more on docs.microsoft.com. If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call the GetLastError function. The system maintains a per-process reference count for each loaded module. A module that was loaded at process initialization due to load-time dynamic linking has a reference count of one. The reference count for a module is incremented each time the module is loaded by a call to LoadLibrary. The reference count is also incremented by a call to LoadLibraryEx unless the module is being loaded for the first time and is being loaded as a data or image file. The reference count is decremented each time the FreeLibrary or FreeLibraryAndExitThread function is called for the module. When a module's reference count reaches zero or the process terminates, the system unloads the module from the address space of the process. Before unloading a library module, the system enables the module to detach from the process by calling the module's DllMain function, if it has one, with the DLL_PROCESS_DETACH value. Doing so gives the library module an opportunity to clean up resources allocated on behalf of the current process. After the entry-point function returns, the library module is removed from the address space of the current process. It is not safe to call FreeLibrary from DllMain. For more information, see the Remarks section in DllMain. Calling FreeLibrary does not affect other processes that are using the same module. Use caution when calling FreeLibrary with a handle returned by GetModuleHandle. The GetModuleHandle function does not increment a module's reference count, so passing this handle to FreeLibrary can cause a module to be unloaded prematurely. A thread that must unload the DLL in which it is executing and then terminate itself should call FreeLibraryAndExitThread instead of calling FreeLibrary and ExitThread separately. Otherwise, a race condition can occur. For details, see the Remarks section of FreeLibraryAndExitThread. Read more on docs.microsoft.com. Maps a character string to a UTF-16 (wide character) string. Code page to use in performing the conversion. This parameter can be set to the value of any code page that is installed or available in the operating system. For a list of code pages, see Code Page Identifiers. Your application can also specify one of the values shown in the following table. This doc was truncated. Read more on docs.microsoft.com. Pointer to the character string to convert. Size, in bytes, of the string indicated by the lpMultiByteStr parameter. Alternatively, this parameter can be set to -1 if the string is null-terminated. Note that, if cbMultiByte is 0, the function fails. If this parameter is -1, the function processes the entire input string, including the terminating null character. Therefore, the resulting Unicode string has a terminating null character, and the length returned by the function includes this character. If this parameter is set to a positive integer, the function processes exactly the specified number of bytes. If the provided size does not include a terminating null character, the resulting Unicode string is not null-terminated, and the returned length does not include this character. Read more on docs.microsoft.com. Pointer to a buffer that receives the converted string. Size, in characters, of the buffer indicated by lpWideCharStr. If this value is 0, the function returns the required buffer size, in characters, including any terminating null character, and makes no use of the lpWideCharStr buffer. Returns the number of characters written to the buffer indicated by lpWideCharStr if successful. If the function succeeds and cchWideChar is 0, the return value is the required size, in characters, for the buffer indicated by lpWideCharStr. Also see dwFlags for info about how the MB_ERR_INVALID_CHARS flag affects the return value when invalid sequences are input. The function returns 0 if it does not succeed. To get extended error information, the application can call GetLastError, which can return one of the following error codes: This doc was truncated. The default behavior of this function is to translate to a precomposed form of the input character string. If a precomposed form does not exist, the function attempts to translate to a composite form. The use of the MB_PRECOMPOSED flag has very little effect on most code pages because most input data is composed already. Consider calling NormalizeString after converting with MultiByteToWideChar. NormalizeString provides more accurate, standard, and consistent data, and can also be faster. Note that for the NORM_FORM enumeration being passed to NormalizeString, NormalizationC corresponds to MB_PRECOMPOSED and NormalizationD corresponds to MB_COMPOSITE. As mentioned in the caution above, the output buffer can easily be overrun if this function is not first called with cchWideChar set to 0 in order to obtain the required size. If the MB_COMPOSITE flag is used, the output can be three or more characters long for each input character. The lpMultiByteStr and lpWideCharStr pointers must not be the same. If they are the same, the function fails, and GetLastError returns the value ERROR_INVALID_PARAMETER. MultiByteToWideChar does not null-terminate an output string if the input string length is explicitly specified without a terminating null character. To null-terminate an output string for this function, the application should pass in -1 or explicitly count the terminating null character for the input string. The function fails if MB_ERR_INVALID_CHARS is set and an invalid character is encountered in the source string. An invalid character is one of the following: This doc was truncated. Read more on docs.microsoft.com. Maps a UTF-16 (wide character) string to a new character string. Code page to use in performing the conversion. This parameter can be set to the value of any code page that is installed or available in the operating system. For a list of code pages, see Code Page Identifiers. Your application can also specify one of the values shown in the following table. This doc was truncated. Read more on docs.microsoft.com. Pointer to the Unicode string to convert. Size, in characters, of the string indicated by lpWideCharStr. Alternatively, this parameter can be set to -1 if the string is null-terminated. If cchWideChar is set to 0, the function fails. If this parameter is -1, the function processes the entire input string, including the terminating null character. Therefore, the resulting character string has a terminating null character, and the length returned by the function includes this character. If this parameter is set to a positive integer, the function processes exactly the specified number of characters. If the provided size does not include a terminating null character, the resulting character string is not null-terminated, and the returned length does not include this character. Read more on docs.microsoft.com. Pointer to a buffer that receives the converted string. Size, in bytes, of the buffer indicated by lpMultiByteStr. If this value is 0, the function returns the required buffer size, in bytes, including any terminating null character, and makes no use of the lpMultiByteStr buffer. Pointer to the character to use if a character cannot be represented in the specified code page. The application sets this parameter to NULL if the function is to use a system default value. To obtain the system default character, the application can call the GetCPInfo or GetCPInfoEx function. For the CP_UTF7 and CP_UTF8 settings for CodePage, this parameter must be set to NULL. Otherwise, the function fails with ERROR_INVALID_PARAMETER. Read more on docs.microsoft.com. Pointer to a flag that indicates if the function has used a default character in the conversion. The flag is set to TRUE if one or more characters in the source string cannot be represented in the specified code page. Otherwise, the flag is set to FALSE. This parameter can be set to NULL. For the CP_UTF7 and CP_UTF8 settings for CodePage, this parameter must be set to NULL. Otherwise, the function fails with ERROR_INVALID_PARAMETER. Read more on docs.microsoft.com. If successful, returns the number of bytes written to the buffer pointed to by lpMultiByteStr. If the function succeeds and cbMultiByte is 0, the return value is the required size, in bytes, for the buffer indicated by lpMultiByteStr. Also see dwFlags for info about how the WC_ERR_INVALID_CHARS flag affects the return value when invalid sequences are input. The function returns 0 if it does not succeed. To get extended error information, the application can call GetLastError, which can return one of the following error codes: This doc was truncated. The lpMultiByteStr and lpWideCharStr pointers must not be the same. If they are the same, the function fails, and GetLastError returns ERROR_INVALID_PARAMETER. WideCharToMultiByte does not null-terminate an output string if the input string length is explicitly specified without a terminating null character. To null-terminate an output string for this function, the application should pass in -1 or explicitly count the terminating null character for the input string. If cbMultiByte is less than cchWideChar, this function writes the number of characters specified by cbMultiByte to the buffer indicated by lpMultiByteStr. However, if CodePage is set to CP_SYMBOL and cbMultiByte is less than cchWideChar, the function writes no characters to lpMultiByteStr. The WideCharToMultiByte function operates most efficiently when both lpDefaultChar and lpUsedDefaultChar are set to NULL. The following table shows the behavior of the function for the four possible combinations of these parameters. This doc was truncated. Read more on docs.microsoft.com. Creates a single uninitialized object of the class associated with a specified CLSID. The CLSID associated with the data and code that will be used to create the object. If NULL, indicates that the object is not being created as part of an aggregate. If non-NULL, pointer to the aggregate object's IUnknown interface (the controlling IUnknown). Context in which the code that manages the newly created object will run. The values are taken from the enumeration CLSCTX. A reference to the identifier of the interface to be used to communicate with the object. Address of pointer variable that receives the interface pointer requested in riid. Upon successful return, *ppv contains the requested interface pointer. Upon failure, *ppv contains NULL. This function can return the following values. This doc was truncated. The CoCreateInstance function provides a convenient shortcut by connecting to the class object associated with the specified CLSID, creating a default-initialized instance, and releasing the class object. As such, it encapsulates the following functionality: This doc was truncated. Read more on docs.microsoft.com. Carries out an OLE drag and drop operation. Pointer to the IDataObject interface on a data object that contains the data being dragged. Pointer to an implementation of the IDropSource interface, which is used to communicate with the source during the drag operation. Effects the source allows in the OLE drag-and-drop operation. Most significant is whether it permits a move. The dwOKEffect and pdwEffect parameters obtain values from the DROPEFFECT enumeration. For a list of values, see DROPEFFECT. Pointer to a value that indicates how the OLE drag-and-drop operation affected the source data. The pdwEffect parameter is set only if the operation is not canceled. This function returns S_OK on success. Other possible values include the following. This doc was truncated. If you are developing an application that can act as a data source for an OLE drag-and-drop operation, you must call DoDragDrop when you detect that the user has started an OLE drag-and-drop operation. The DoDragDrop function enters a loop in which it calls various methods in the IDropSource and IDropTarget interfaces. (For a successful drag-and-drop operation, the application acting as the data source must also implement IDropSource, while the target application must implement IDropTarget.) This doc was truncated. Read more on docs.microsoft.com. Duplicates the data found in the specified handle and returns a handle to the duplicated data. The source data is in a clipboard format. Use this function to help implement some of the data transfer interfaces such as IDataObject. Handle of the source data. Clipboard format of the source data. Flags to be used to allocate global memory for the copied data. These flags are passed to GlobalAlloc. If the value of uiFlags is NULL, GMEM_MOVEABLE is used as a default flag. On success the HANDLE to the source data is returned; on failure a NULL value is returned. The CF_METAFILEPICT, CF_PALETTE, or CF_BITMAP formats receive special handling. They are GDI handles and a new GDI object must be created instead of just copying the bytes. All other formats are duplicated byte-wise. Carries out the clipboard shutdown sequence. It also releases the IDataObject pointer that was placed on the clipboard by the OleSetClipboard function. This function returns S_OK on success. Other possible values include the following. This doc was truncated. OleFlushClipboard renders the data from a data object onto the clipboard and releases the IDataObject pointer to the data object. While the application that put the data object on the clipboard is running, the clipboard holds only a pointer to the data object, thus saving memory. If you are writing an application that acts as the source of a clipboard operation, you can call the OleFlushClipboard function when your application is closed, such as when the user exits from your application. Calling OleFlushClipboard enables pasting and paste-linking of OLE objects after application shutdown. Before calling OleFlushClipboard, you can easily determine if your data is still on the clipboard with a call to the OleIsCurrentClipboard function. OleFlushClipboard leaves all formats offered by the data transfer object, including the OLE 1 compatibility formats, on the clipboard so they are available after application shutdown. In addition to OLE 1 compatibility formats, these include all formats offered on a global handle medium (all except for TYMED_FILE) and formatted with a NULL target device. For example, if a data-source application offers a particular clipboard format (say cfFOO) on an IStorage object, and calls the OleFlushClipboard function, the storage object is copied into memory and the hglobal memory handle is put on the clipboard. To retrieve the information on the clipboard, you can call the OleGetClipboard function from another application, which creates a default data object, and the hglobal from the clipboard again becomes a storage object. Furthermore, the FORMATETC enumerator and the IDataObject::QueryGetData method would all correctly indicate that the original clipboard format (cfFOO) is again available on a TYMED_ISTORAGE. To empty the clipboard, call the OleSetClipboard function specifying a NULL value for its parameter. The application should call this when it closes if there is no need to leave data on the clipboard after shutdown, or if data will be placed on the clipboard using the standard Windows clipboard functions. Read more on docs.microsoft.com. Retrieves a data object that you can use to access the contents of the clipboard. Address of IDataObject pointer variable that receives the interface pointer to the clipboard data object. This function returns S_OK on success. Other possible values include the following. This doc was truncated.
Caution  Clipboard data is not trusted. Parse the data carefully before using it in your application.
 
If you are writing an application that can accept data from the clipboard, call the OleGetClipboard function to get a pointer to the IDataObject interface that you can use to retrieve the contents of the clipboard. OleGetClipboard handles three cases: This doc was truncated. Read more on docs.microsoft.com. Initializes the COM library on the current apartment, identifies the concurrency model as single-thread apartment (STA), and enables additional functionality described in the Remarks section below. This parameter is reserved and must be NULL. This function returns S_OK on success. Other possible values include the following. This doc was truncated. Applications that use the following functionality must call OleInitialize before calling any other function in the COM library: This doc was truncated. Read more on docs.microsoft.com. Places a pointer to a specific data object onto the clipboard. This makes the data object accessible to the OleGetClipboard function. Pointer to the IDataObject interface on the data object from which the data to be placed on the clipboard can be obtained. This parameter can be NULL; in which case the clipboard is emptied. This function returns S_OK on success. Other possible values include the following. This doc was truncated. If you are writing an application that can act as the source of a clipboard operation, you must do the following: This doc was truncated. Read more on docs.microsoft.com. Closes the COM library on the apartment, releases any class factories, other COM objects, or servers held by the apartment, disables RPC on the apartment, and frees any resources the apartment maintains. Call OleUninitialize on application shutdown, as the last COM library call, if the apartment was initialized with a call to OleInitialize. OleUninitialize calls the CoUninitialize function internally to shut down the OLE Component Object(COM) Library. If the COM library was initialized on the apartment with a call to CoInitialize or CoInitializeEx, it must be closed with a call to CoUninitialize. The OleInitialize and OleUninitialize calls must be balanced. If there are multiple calls to the OleInitialize function, there must be the same number of calls to OleUninitialize; only the OleUninitialize call corresponding to the OleInitialize call that actually initialized the library can close it. Because there is no way to control the order in which in-process servers are loaded or unloaded, do not call OleInitialize or OleUninitialize from the DllMain function. Read more on docs.microsoft.com. Frees all elements that can be freed in a given PROPVARIANT structure. A pointer to an initialized PROPVARIANT structure for which any deallocatable elements are to be freed. On return, all zeroes are written to the PROPVARIANT structure. Read more on docs.microsoft.com. This function returns HRESULT. At any level of indirection, NULL pointers are ignored. For example, the pvar parameter points to a PROPVARIANT structure of type VT_CF. The pclipdata member of the PROPVARIANT structure points to a CLIPDATA structure. The pClipData pointer in the CLIPDATA structure is NULL. In this example, the pClipData pointer is ignored. However, the CLIPDATA structure pointed to by the pclipdata member of the PROPVARIANT structure is freed. On return, this function writes zeroes to the specified PROPVARIANT structure, so the VT-type is VT_EMPTY. Passing NULL as the pvar parameter produces a return code of S_OK.
Note  Do not use this function to initialize PROPVARIANT structures. Instead, initialize these structures using the PropVariantInit macro (defined in Propidl.h).
 
 Read more on docs.microsoft.com. Registers the specified window as one that can be the target of an OLE drag-and-drop operation and specifies the IDropTarget instance to use for drop operations. Handle to a window that can be a target for an OLE drag-and-drop operation. Pointer to the IDropTarget interface on the object that is to be the target of a drag-and-drop operation in a specified window. This interface is used to communicate OLE drag-and-drop information for that window. This function returns S_OK on success. Other possible values include the following. This doc was truncated. If your application can accept dropped objects during OLE drag-and-drop operations, you must call the RegisterDragDrop function. Do this whenever one of your application windows is available as a potential drop target, i.e., when the window appears unobscured on the screen. The application thread that calls the RegisterDragDrop function must be pumping messages, presumably by calling the GetMessage function with a NULLhWnd parameter, because OLE creates windows on the thread that need messages processed. If this requirement is not met, any application that drags an object over the window that is registered as a drop target will hang until the target application closes. The RegisterDragDrop function only registers one window at a time, so you must call it for each application window capable of accepting dropped objects. As the mouse passes over unobscured portions of the target window during an OLE drag-and-drop operation, the DoDragDrop function calls the specified IDropTarget::DragOver method for the current window. When a drop operation actually occurs in a given window, the DoDragDrop function calls IDropTarget::Drop. The RegisterDragDrop function also calls the IUnknown::AddRef method on the IDropTarget pointer. Read more on docs.microsoft.com. Frees the specified storage medium. The ReleaseStgMedium function calls the appropriate method or function to release the specified storage medium. Use this function during data transfer operations where storage medium structures are parameters, such as IDataObject::GetData or IDataObject::SetData. In addition to identifying the type of the storage medium, this structure specifies the appropriate Release method for releasing the storage medium when it is no longer needed. It is common to pass a STGMEDIUM from one body of code to another, such as in IDataObject::GetData, in which the one called can allocate a medium and return it to the caller. ReleaseStgMedium permits flexibility in whether the receiving body of code owns the medium, or whether the original provider of the medium still owns it, in which case the receiving code needs to inform the provider that it can free the medium. When the original provider of the medium is responsible for freeing the medium, the provider calls ReleaseStgMedium, specifying the medium and the appropriate IUnknown pointer as the punkForRelease structure member. Depending on the type of storage medium being freed, one of the following actions is taken, followed by a call to the IUnknown::Release method on the specified IUnknown pointer. This doc was truncated. Read more on docs.microsoft.com. Revokes the registration of the specified application window as a potential target for OLE drag-and-drop operations. Handle to a window previously registered as a target for an OLE drag-and-drop operation. This function returns S_OK on success. Other possible values include the following. This doc was truncated. When your application window is no longer available as a potential target for an OLE drag-and-drop operation, you must call RevokeDragDrop. This function calls the IUnknown::Release method for your drop target interface. Read more on docs.microsoft.com. Deallocates a string allocated previously by SysAllocString, SysAllocStringByteLen, SysReAllocString, SysAllocStringLen, or SysReAllocStringLen. The previously allocated string. If this parameter is NULL, the function simply returns. Learn more about this API from docs.microsoft.com. Uses registry information to load a type library. The GUID of the library. The major version of the library. The minor version of the library. The national language code of the library. The loaded type library. This function can return one of these values. This doc was truncated. The function LoadRegTypeLib defers to LoadTypeLib to load the file. LoadRegTypeLib compares the requested version numbers against those found in the system registry, and takes one of the following actions: This doc was truncated. Read more on docs.microsoft.com. Creates a new picture object initialized according to a PICTDESC structure. Pointer to a caller-allocated structure containing the initial state of the picture. The specified structure can be NULL to create an uninitialized object, in the event the picture needs to initialize via IPersistStream::Load. Reference to the identifier of the interface describing the type of interface pointer to return in lplpvObj. If TRUE, the picture object is to destroy its picture when the object is destroyed. If FALSE, the caller is responsible for destroying the picture. Address of pointer variable that receives the interface pointer requested in riid. Upon successful return, this parameter contains the requested interface pointer on the newly created object. If the call is successful, the caller is responsible for calling Release through this interface pointer when the new object is no longer needed. If the call fails, the value is set to NULL. This function returns S_OK on success. Other possible values include the following. This doc was truncated. The fOwn parameter indicates whether the picture is to own the GDI picture handle for the picture it contains, so that the picture object will destroy its picture when the object itself is destroyed. The function returns an interface pointer to the new picture object specified by the caller in the riid parameter. A QueryInterface is built into this call. The caller is responsible for calling Release through the interface pointer returned. Creates a new array descriptor, allocates and initializes the data for the array, and returns a pointer to the new array descriptor. The base type of the array (the VARTYPE of each element of the array). The VARTYPE is restricted to a subset of the variant types. Neither the VT_ARRAY nor the VT_BYREF flag can be set. VT_EMPTY and VT_NULL are not valid base types for the array. All other types are legal. The number of dimensions in the array. The number cannot be changed after the array is created. A vector of bounds (one for each dimension) to allocate for the array. A safe array descriptor, or null if the array could not be created. Learn more about this API from docs.microsoft.com. Creates and returns a safe array descriptor from the specified VARTYPE, number of dimensions and bounds. The base type or the VARTYPE of each element of the array. The FADF_RECORD flag can be set for a variant type VT_RECORD, The FADF_HAVEIID flag can be set for VT_DISPATCH or VT_UNKNOWN, and FADF_HAVEVARTYPE can be set for all other VARTYPEs. The number of dimensions in the array. A vector of bounds (one for each dimension) to allocate for the array. the type information of the user-defined type, if you are creating a safe array of user-defined types. If the vt parameter is VT_RECORD, then pvExtra will be a pointer to an IRecordInfo describing the record. If the vt parameter is VT_DISPATCH or VT_UNKNOWN, then pvExtra will contain a pointer to a GUID representing the type of interface being passed to the array. A safe array descriptor, or null if the array could not be created. If the VARTYPE is VT_RECORD then SafeArraySetRecordInfo is called. If the VARTYPE is VT_DISPATCH or VT_UNKNOWN then the elements of the array must contain interfaces of the same type. Part of the process of marshaling this array to other processes does include generating the proxy/stub code of the IID pointed to by the pvExtra parameter. To actually pass heterogeneous interfaces one will need to specify either IID_IUnknown or IID_IDispatch in pvExtra and provide some other means for the caller to identify how to query for the actual interface. Destroys an existing array descriptor and all of the data in the array. An array descriptor created by SafeArrayCreate. This function can return one of these values. This doc was truncated. Safe arrays of variant will have the VariantClear function called on each member and safe arrays of BSTR will have the SysFreeString function called on each element. IRecordInfo::RecordClear will be called to release object references and other values of a record without deallocating the record. Retrieves a single element of the array. An array descriptor created by SafeArrayCreate. A vector of indexes for each dimension of the array. The right-most (least significant) dimension is rgIndices[0]. The left-most dimension is stored at rgIndices[psa->cDims – 1]. The element of the array. This function can return one of these values. This doc was truncated. This function calls SafeArrayLock and SafeArrayUnlock automatically, before and after retrieving the element. The caller must provide a storage area of the correct size to receive the data. If the data element is a string, object, or variant, the function copies the element in the correct way. Retrieves the IRecordInfo interface of the UDT contained in the specified safe array. An array descriptor created by SafeArrayCreate. The IRecordInfo interface. This function can return one of these values. This doc was truncated. Learn more about this API from docs.microsoft.com. Gets the VARTYPE stored in the specified safe array. An array descriptor created by SafeArrayCreate. The VARTYPE. This function can return one of these values. This doc was truncated. If FADF_HAVEVARTYPE is set, SafeArrayGetVartype returns the VARTYPE stored in the array descriptor. If FADF_RECORD is set, it returns VT_RECORD; if FADF_DISPATCH is set, it returns VT_DISPATCH; and if FADF_UNKNOWN is set, it returns VT_UNKNOWN. SafeArrayGetVartype can fail to return VT_UNKNOWN for SAFEARRAY types that are based on IUnknown. Callers should additionally check whether the SAFEARRAY type's fFeatures field has the FADF_UNKNOWN flag set. Read more on docs.microsoft.com. Increments the lock count of an array, and places a pointer to the array data in pvData of the array descriptor. An array descriptor created by SafeArrayCreate. This function can return one of these values. This doc was truncated. The pointer in the array descriptor is valid until the SafeArrayUnlock function is called. Calls to SafeArrayLock can be nested, in which case an equal number of calls to SafeArrayUnlock are required. An array cannot be deleted while it is locked. Read more on docs.microsoft.com. Stores the data element at the specified location in the array. An array descriptor created by SafeArrayCreate. A vector of indexes for each dimension of the array. The right-most (least significant) dimension is rgIndices[0]. The left-most dimension is stored at rgIndices[psa->cDims – 1]. The data to assign to the array. The variant types VT_DISPATCH, VT_UNKNOWN, and VT_BSTR are pointers, and do not require another level of indirection. This function can return one of these values. This doc was truncated. This function automatically calls SafeArrayLock and SafeArrayUnlock before and after assigning the element. If the data element is a string, object, or variant, the function copies it correctly when the safe array is destroyed. If the existing element is a string, object, or variant, it is cleared correctly. If the data element is a VT_DISPATCH or VT_UNKNOWN, AddRef is called to increment the object's reference count.
Note  Multiple locks can be on an array. Elements can be put into an array while the array is locked by other operations.
 
For an example that demonstrates calling SafeArrayPutElement, see the COM Fundamentals Lines sample (CLines::Add in Lines.cpp). Read more on docs.microsoft.com. Decrements the lock count of an array so it can be freed or resized. An array descriptor created by SafeArrayCreate. This function can return one of these values. This doc was truncated. This function is called after access to the data in an array is finished. Registers whether a window accepts dropped files. Type: HWND The identifier of the window that is registering whether it will accept dropped files. Read more on docs.microsoft.com. Type: BOOL A value that indicates if the window identified by the hWnd parameter accepts dropped files. This value is TRUE to accept dropped files or FALSE to discontinue accepting dropped files. Read more on docs.microsoft.com. An application that calls DragAcceptFiles with the fAccept parameter set to TRUE has identified itself as able to process the WM_DROPFILES message from File Manager. Retrieves the names of dropped files that result from a successful drag-and-drop operation. (Unicode) Type: HDROP Identifier of the structure that contains the file names of the dropped files. Read more on docs.microsoft.com. Type: UINT Index of the file to query. If the value of this parameter is 0xFFFFFFFF, DragQueryFile returns a count of the files dropped. If the value of this parameter is between zero and the total number of files dropped, DragQueryFile copies the file name with the corresponding value to the buffer pointed to by the lpszFile parameter. Read more on docs.microsoft.com. Type: LPTSTR The address of a buffer that receives the file name of a dropped file when the function returns. This file name is a null-terminated string. If this parameter is NULL, DragQueryFile returns the required size, in characters, of this buffer. Read more on docs.microsoft.com. Type: UINT The size, in characters, of the lpszFile buffer. Read more on docs.microsoft.com. Type: UINT A nonzero value indicates a successful call. When the function copies a file name to the buffer, the return value is a count of the characters copied, not including the terminating null character. If the index value is 0xFFFFFFFF, the return value is a count of the dropped files. Note that the index variable itself returns unchanged, and therefore remains 0xFFFFFFFF. If the index value is between zero and the total number of dropped files, and the lpszFile buffer address is NULL, the return value is the required size, in characters, of the buffer, not including the terminating null character. > [!NOTE] > The shellapi.h header defines DragQueryFile as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see [Conventions for Function Prototypes](/windows/win32/intl/conventions-for-function-prototypes). Read more on docs.microsoft.com. The BeginPaint function prepares the specified window for painting and fills a PAINTSTRUCT structure with information about the painting. Handle to the window to be repainted. Pointer to the PAINTSTRUCT structure that will receive painting information. If the function succeeds, the return value is the handle to a display device context for the specified window. If the function fails, the return value is NULL, indicating that no display device context is available. The BeginPaint function automatically sets the clipping region of the device context to exclude any area outside the update region. The update region is set by the InvalidateRect or InvalidateRgn function and by the system after sizing, moving, creating, scrolling, or any other operation that affects the client area. If the update region is marked for erasing, BeginPaint sends a WM_ERASEBKGND message to the window. An application should not call BeginPaint except in response to a WM_PAINT message. Each call to BeginPaint must have a corresponding call to the EndPaint function. If the caret is in the area to be painted, BeginPaint automatically hides the caret to prevent it from being erased. If the window's class has a background brush, BeginPaint uses that brush to erase the background of the update region before returning.

DPI Virtualization

This API does not participate in DPI virtualization. The output returned is always in terms of physical pixels. Read more on docs.microsoft.com. Passes message information to the specified window procedure. (Unicode) Type: WNDPROC The previous window procedure. If this value is obtained by calling the GetWindowLong function with the nIndex parameter set to GWL_WNDPROC or DWL_DLGPROC, it is actually either the address of a window or dialog box procedure, or a special internal value meaningful only to CallWindowProc. Read more on docs.microsoft.com. Type: HWND A handle to the window procedure to receive the message. Read more on docs.microsoft.com. Type: UINT The message. Read more on docs.microsoft.com. Type: WPARAM Additional message-specific information. The contents of this parameter depend on the value of the Msg parameter. Read more on docs.microsoft.com. Type: LPARAM Additional message-specific information. The contents of this parameter depend on the value of the Msg parameter. Read more on docs.microsoft.com. Type: LRESULT The return value specifies the result of the message processing and depends on the message sent. Use the CallWindowProc function for window subclassing. Usually, all windows with the same class share one window procedure. A subclass is a window or set of windows with the same class whose messages are intercepted and processed by another window procedure (or procedures) before being passed to the window procedure of the class. The SetWindowLong function creates the subclass by changing the window procedure associated with a particular window, causing the system to call the new window procedure instead of the previous one. An application must pass any messages not processed by the new window procedure to the previous window procedure by calling CallWindowProc. This allows the application to create a chain of window procedures. If STRICT is defined, the lpPrevWndFunc parameter has the data type WNDPROC. The WNDPROC type is declared as follows: This doc was truncated. Read more on docs.microsoft.com. Creates a new image (icon, cursor, or bitmap) and copies the attributes of the specified image to the new one. If necessary, the function stretches the bits to fit the desired size of the new image. Type: HANDLE A handle to the image to be copied. Read more on docs.microsoft.com. Type: UINT Type: int The desired width, in pixels, of the image. If this is zero, then the returned image will have the same width as the original hImage. Read more on docs.microsoft.com. Type: int The desired height, in pixels, of the image. If this is zero, then the returned image will have the same height as the original hImage. Read more on docs.microsoft.com. Type: UINT Type: HANDLE If the function succeeds, the return value is the handle to the newly created image. If the function fails, the return value is NULL. To get extended error information, call GetLastError. When you are finished using the resource, you can release its associated memory by calling one of the functions in the following table. This doc was truncated. Read more on docs.microsoft.com. Calls the default window procedure to provide default processing for any window messages that an application does not process. (Unicode) Type: HWND A handle to the window procedure that received the message. Read more on docs.microsoft.com. Type: UINT The message. Read more on docs.microsoft.com. Type: WPARAM Additional message information. The content of this parameter depends on the value of the Msg parameter. Read more on docs.microsoft.com. Type: LPARAM Additional message information. The content of this parameter depends on the value of the Msg parameter. Read more on docs.microsoft.com. Type: LRESULT The return value is the result of the message processing and depends on the message. > [!NOTE] > The winuser.h header defines DefWindowProc as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see [Conventions for Function Prototypes](/windows/win32/intl/conventions-for-function-prototypes). Read more on docs.microsoft.com. Destroys an icon and frees any memory the icon occupied. Type: HICON A handle to the icon to be destroyed. The icon must not be in use. Read more on docs.microsoft.com. Type: BOOL If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError. It is only necessary to call DestroyIcon for icons and cursors created with the following functions: CreateIconFromResourceEx (if called without the LR_SHARED flag), CreateIconIndirect, and CopyIcon. Do not use this function to destroy a shared icon. A shared icon is valid as long as the module from which it was loaded remains in memory. The following functions obtain a shared icon. This doc was truncated. Read more on docs.microsoft.com. Draws an icon or cursor into the specified device context, performing the specified raster operations, and stretching or compressing the icon or cursor as specified. Type: HDC A handle to the device context into which the icon or cursor will be drawn. Read more on docs.microsoft.com. Type: int The logical x-coordinate of the upper-left corner of the icon or cursor. Read more on docs.microsoft.com. Type: int The logical y-coordinate of the upper-left corner of the icon or cursor. Read more on docs.microsoft.com. Type: HICON A handle to the icon or cursor to be drawn. This parameter can identify an animated cursor. Read more on docs.microsoft.com. Type: int The logical width of the icon or cursor. If this parameter is zero and the diFlags parameter is DI_DEFAULTSIZE, the function uses the SM_CXICON system metric value to set the width. If this parameter is zero and DI_DEFAULTSIZE is not used, the function uses the actual resource width. Read more on docs.microsoft.com. Type: int The logical height of the icon or cursor. If this parameter is zero and the diFlags parameter is DI_DEFAULTSIZE, the function uses the SM_CYICON system metric value to set the width. If this parameter is zero and DI_DEFAULTSIZE is not used, the function uses the actual resource height. Read more on docs.microsoft.com. Type: UINT The index of the frame to draw, if hIcon identifies an animated cursor. This parameter is ignored if hIcon does not identify an animated cursor. Read more on docs.microsoft.com. Type: HBRUSH A handle to a brush that the system uses for flicker-free drawing. If hbrFlickerFreeDraw is a valid brush handle, the system creates an offscreen bitmap using the specified brush for the background color, draws the icon or cursor into the bitmap, and then copies the bitmap into the device context identified by hdc. If hbrFlickerFreeDraw is NULL, the system draws the icon or cursor directly into the device context. Read more on docs.microsoft.com. Type: UINT Type: BOOL If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError. The DrawIconEx function places the icon's upper-left corner at the location specified by the xLeft and yTop parameters. The location is subject to the current mapping mode of the device context. If only one of the DI_IMAGE and DI_MASK flags is set, then the corresponding bitmap is drawn with the SRCCOPY raster operation code. If both the DI_IMAGE and DI_MASK flags are set: * If the icon or cursor is a 32-bit alpha-blended icon or cursor, then the image is drawn with AC_SRC_OVER blend function and the mask is ignored. * For all other icons or cursors, the mask is drawn with the SRCAND raster operation code, and the image is drawn with the SRCINVERT raster operation code To duplicate DrawIcon (hDC, X, Y, hIcon), call DrawIconEx as follows: This doc was truncated. Read more on docs.microsoft.com. The EndPaint function marks the end of painting in the specified window. This function is required for each call to the BeginPaint function, but only after painting is complete. Handle to the window that has been repainted. Pointer to a PAINTSTRUCT structure that contains the painting information retrieved by BeginPaint. The return value is always nonzero. If the caret was hidden by BeginPaint, EndPaint restores the caret to the screen. EndPaint releases the display device context that BeginPaint retrieved. Read more on docs.microsoft.com. Enumerates the child windows that belong to the specified parent window by passing the handle to each child window, in turn, to an application-defined callback function. Type: HWND A handle to the parent window whose child windows are to be enumerated. If this parameter is NULL, this function is equivalent to EnumWindows. Read more on docs.microsoft.com. Type: WNDENUMPROC A pointer to an application-defined callback function. For more information, see EnumChildProc. Read more on docs.microsoft.com. Type: LPARAM An application-defined value to be passed to the callback function. Read more on docs.microsoft.com. Type: BOOL The return value is not used. If a child window has created child windows of its own, EnumChildWindows enumerates those windows as well. A child window that is moved or repositioned in the Z order during the enumeration process will be properly enumerated. The function does not enumerate a child window that is destroyed before being enumerated or that is created during the enumeration process. Read more on docs.microsoft.com. The EnumDisplayMonitors function enumerates display monitors (including invisible pseudo-monitors associated with the mirroring drivers) that intersect a region formed by the intersection of a specified clipping rectangle and the visible region of a device context. EnumDisplayMonitors calls an application-defined MonitorEnumProc callback function once for each monitor that is enumerated. Note that GetSystemMetrics (SM_CMONITORS) counts only the display monitors. A handle to a display device context that defines the visible region of interest. If this parameter is NULL, the hdcMonitor parameter passed to the callback function will be NULL, and the visible region of interest is the virtual screen that encompasses all the displays on the desktop. Read more on docs.microsoft.com. A pointer to a RECT structure that specifies a clipping rectangle. The region of interest is the intersection of the clipping rectangle with the visible region specified by hdc. If hdc is non-NULL, the coordinates of the clipping rectangle are relative to the origin of the hdc. If hdc is NULL, the coordinates are virtual-screen coordinates. This parameter can be NULL if you don't want to clip the region specified by hdc. Read more on docs.microsoft.com. A pointer to a MonitorEnumProc application-defined callback function. Application-defined data that EnumDisplayMonitors passes directly to the MonitorEnumProc function. If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. There are two reasons to call the EnumDisplayMonitors function: This doc was truncated. Read more on docs.microsoft.com. Enumerates all nonchild windows associated with a thread by passing the handle to each window, in turn, to an application-defined callback function. Type: DWORD The identifier of the thread whose windows are to be enumerated. Read more on docs.microsoft.com. Type: WNDENUMPROC A pointer to an application-defined callback function. For more information, see EnumThreadWndProc. Read more on docs.microsoft.com. Type: LPARAM An application-defined value to be passed to the callback function. Read more on docs.microsoft.com. Type: BOOL If the callback function returns TRUE for all windows in the thread specified by dwThreadId, the return value is TRUE. If the callback function returns FALSE on any enumerated window, or if there are no windows found in the thread specified by dwThreadId, the return value is FALSE. Learn more about this API from docs.microsoft.com. Enumerates all top-level windows on the screen by passing the handle to each window, in turn, to an application-defined callback function. EnumWindows continues until the last top-level window is enumerated or the callback function returns FALSE. Type: WNDENUMPROC A pointer to an application-defined callback function. For more information, see EnumWindowsProc. Read more on docs.microsoft.com. Type: LPARAM An application-defined value to be passed to the callback function. Read more on docs.microsoft.com. Type: BOOL If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError. If EnumWindowsProc returns zero, the return value is also zero. In this case, the callback function should call SetLastError to obtain a meaningful error code to be returned to the caller of EnumWindows. The EnumWindows function does not enumerate child windows, with the exception of a few top-level windows owned by the system that have the WS_CHILD style. This function is more reliable than calling the GetWindow function in a loop. An application that calls GetWindow to perform this task risks being caught in an infinite loop or referencing a handle to a window that has been destroyed.
Note  For Windows 8 and later, EnumWindows enumerates only top-level windows of desktop apps.
 
 Read more on docs.microsoft.com. Retrieves the coordinates of a window's client area. Type: HWND A handle to the window whose client coordinates are to be retrieved. Read more on docs.microsoft.com. Type: LPRECT A pointer to a RECT structure that receives the client coordinates. The left and top members are zero. The right and bottom members contain the width and height of the window. Read more on docs.microsoft.com. Type: BOOL If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError. In conformance with conventions for the RECT structure, the bottom-right coordinates of the returned rectangle are exclusive. In other words, the pixel at (right, bottom) lies immediately outside the rectangle. Retrieves from the clipboard the name of the specified registered format. The function copies the name to the specified buffer. (Unicode) Type: UINT The type of format to be retrieved. This parameter must not specify any of the predefined clipboard formats. Read more on docs.microsoft.com. Type: LPTSTR The buffer that is to receive the format name. Read more on docs.microsoft.com. Type: int The maximum length, in characters, of the string to be copied to the buffer. If the name exceeds this limit, it is truncated. Read more on docs.microsoft.com. Type: int If the function succeeds, the return value is the length, in characters, of the string copied to the buffer. If the function fails, the return value is zero, indicating that the requested format does not exist or is predefined. To get extended error information, call GetLastError.

Security Considerations

Using this function incorrectly might compromise the security of your program. For example, miscalculating the proper size of the lpszFormatName buffer, especially when the application is used in both ANSI and Unicode versions, can cause a buffer overflow. Also, note that the string is truncated if it is longer than the cchMaxCount parameter, which can lead to loss of information. Read more on docs.microsoft.com. The GetDC function retrieves a handle to a device context (DC) for the client area of a specified window or for the entire screen. A handle to the window whose DC is to be retrieved. If this value is NULL, GetDC retrieves the DC for the entire screen. If the function succeeds, the return value is a handle to the DC for the specified window's client area. If the function fails, the return value is NULL. The GetDC function retrieves a common, class, or private DC depending on the class style of the specified window. For class and private DCs, GetDC leaves the previously assigned attributes unchanged. However, for common DCs, GetDC assigns default attributes to the DC each time it is retrieved. For example, the default font is System, which is a bitmap font. Because of this, the handle to a common DC returned by GetDC does not tell you what font, color, or brush was used when the window was drawn. To determine the font, call GetTextFace. Note that the handle to the DC can only be used by a single thread at any one time. After painting with a common DC, the ReleaseDC function must be called to release the DC. Class and private DCs do not have to be released. ReleaseDC must be called from the same thread that called GetDC. The number of DCs is limited only by available memory. Read more on docs.microsoft.com. The GetDCEx function retrieves a handle to a device context (DC) for the client area of a specified window or for the entire screen. A handle to the window whose DC is to be retrieved. If this value is NULL, GetDCEx retrieves the DC for the entire screen. A clipping region that may be combined with the visible region of the DC. If the value of flags is DCX_INTERSECTRGN or DCX_EXCLUDERGN, then the operating system assumes ownership of the region and will automatically delete it when it is no longer needed. In this case, the application should not use or delete the region after a successful call to GetDCEx. If the function succeeds, the return value is the handle to the DC for the specified window. If the function fails, the return value is NULL. An invalid value for the hWnd parameter will cause the function to fail. Unless the display DC belongs to a window class, the ReleaseDC function must be called to release the DC after painting. Also, ReleaseDC must be called from the same thread that called GetDCEx. The number of DCs is limited only by available memory. The function returns a handle to a DC that belongs to the window's class if CS_CLASSDC, CS_OWNDC or CS_PARENTDC was specified as a style in the WNDCLASS structure when the class was registered. Read more on docs.microsoft.com. Retrieves a handle to the desktop window. The desktop window covers the entire screen. The desktop window is the area on top of which other windows are painted. Type: HWND The return value is a handle to the desktop window. Learn more about this API from docs.microsoft.com. Retrieves a handle to the foreground window (the window with which the user is currently working). The system assigns a slightly higher priority to the thread that creates the foreground window than it does to other threads. Type: HWND The return value is a handle to the foreground window. The foreground window can be NULL in certain circumstances, such as when a window is losing activation. Learn more about this API from docs.microsoft.com. Retrieves the count of handles to graphical user interface (GUI) objects in use by the specified process. A handle to the process. The handle must refer to a process in the current session, and must have the **PROCESS_QUERY_LIMITED_INFORMATION** access right (see [Process security and access rights](/windows/win32/procthread/process-security-and-access-rights)). If this parameter is the special value **GR_GLOBAL**, then the resource usage is reported across all processes in the current session. **Windows Server 2008, Windows Vista, Windows Server 2003, and Windows XP:** The **GR_GLOBAL** value is not supported until Windows 7 and Windows Server 2008 R2. **Windows Server 2003 and Windows XP:** The handle must have the **PROCESS_QUERY_INFORMATION** access right. Read more on docs.microsoft.com. If the function succeeds, the return value is the count of handles to GUI objects in use by the process. If no GUI objects are in use, the return value is zero. If the function fails, the return value is zero. To get extended error information, call GetLastError. A process without a graphical user interface does not use GUI resources, therefore, GetGuiResources will return zero. Read more on docs.microsoft.com. Retrieves information about the specified icon or cursor. Type: HICON Type: PICONINFO A pointer to an ICONINFO structure. The function fills in the structure's members. Read more on docs.microsoft.com. Type: BOOL If the function succeeds, the return value is nonzero and the function fills in the members of the specified ICONINFO structure. If the function fails, the return value is zero. To get extended error information, call GetLastError. GetIconInfo creates bitmaps for the hbmMask and hbmColor or members of ICONINFO. The calling application must manage these bitmaps and delete them when they are no longer necessary.

DPI Virtualization

This API does not participate in DPI virtualization. The output returned is not affected by the DPI of the calling thread. Read more on docs.microsoft.com. The GetMonitorInfo function retrieves information about a display monitor. (Unicode) A handle to the display monitor of interest. A pointer to a MONITORINFO or MONITORINFOEX structure that receives information about the specified display monitor. You must set the cbSize member of the structure to sizeof(MONITORINFO) or sizeof(MONITORINFOEX) before calling the GetMonitorInfo function. Doing so lets the function determine the type of structure you are passing to it. The MONITORINFOEX structure is a superset of the MONITORINFO structure. It has one additional member: a string that contains a name for the display monitor. Most applications have no use for a display monitor name, and so can save some bytes by using a MONITORINFO structure. Read more on docs.microsoft.com. If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. > [!NOTE] > The winuser.h header defines GetMonitorInfo as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see [Conventions for Function Prototypes](/windows/win32/intl/conventions-for-function-prototypes). Read more on docs.microsoft.com. The GetSysColorBrush function retrieves a handle identifying a logical brush that corresponds to the specified color index. A color index. This value corresponds to the color used to paint one of the window elements. See GetSysColor for system color index values. The return value identifies a logical brush if the nIndex parameter is supported by the current platform. Otherwise, it returns NULL. A brush is a bitmap that the system uses to paint the interiors of filled shapes. An application can retrieve the current system colors by calling the GetSysColor function. An application can set the current system colors by calling the SetSysColors function. An application must not register a window class for a window using a system brush. To register a window class with a system color, see the documentation of the hbrBackground member of the WNDCLASS or WNDCLASSEX structures. System color brushes track changes in system colors. In other words, when the user changes a system color, the associated system color brush automatically changes to the new color. To paint with a system color brush, an application should use GetSysColorBrush (nIndex) instead of CreateSolidBrush ( GetSysColor (nIndex)), because GetSysColorBrush returns a cached brush instead of allocating a new one. System color brushes are owned by the system so you don't need to destroy them. Although you don't need to delete the logical brush that GetSysColorBrush returns, no harm occurs by calling DeleteObject. Read more on docs.microsoft.com. Retrieves the specified system metric or system configuration setting. Type: int Type: int If the function succeeds, the return value is the requested system metric or configuration setting. If the function fails, the return value is 0. GetLastError does not provide extended error information. System metrics can vary from display to display. GetSystemMetrics(SM_CMONITORS) counts only visible display monitors. This is different from EnumDisplayMonitors, which enumerates both visible display monitors and invisible pseudo-monitors that are associated with mirroring drivers. An invisible pseudo-monitor is associated with a pseudo-device used to mirror application drawing for remoting or other purposes. The SM_ARRANGE setting specifies how the system arranges minimized windows, and consists of a starting position and a direction. The starting position can be one of the following values. This doc was truncated. Read more on docs.microsoft.com. Retrieves the dimensions of the bounding rectangle of the specified window. The dimensions are given in screen coordinates that are relative to the upper-left corner of the screen. Type: HWND A handle to the window. Read more on docs.microsoft.com. Type: LPRECT A pointer to a RECT structure that receives the screen coordinates of the upper-left and lower-right corners of the window. Read more on docs.microsoft.com. Type: BOOL If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError. In conformance with conventions for the RECT structure, the bottom-right coordinates of the returned rectangle are exclusive. In other words, the pixel at (right, bottom) lies immediately outside the rectangle. GetWindowRect is virtualized for DPI. In Windows Vista and later, the Window Rect now includes the area occupied by the drop shadow. Calling GetWindowRect will have different behavior depending on whether the window has ever been shown or not. If the window has not been shown before, GetWindowRect will not include the area of the drop shadow. To get the window bounds excluding the drop shadow, use DwmGetWindowAttribute, specifying DWMWA_EXTENDED_FRAME_BOUNDS. Note that unlike the Window Rect, the DWM Extended Frame Bounds are not adjusted for DPI. Getting the extended frame bounds can only be done after the window has been shown at least once. Read more on docs.microsoft.com. Copies the text of the specified window's title bar (if it has one) into a buffer. If the specified window is a control, the text of the control is copied. However, GetWindowText cannot retrieve the text of a control in another application. (Unicode) Type: HWND A handle to the window or control containing the text. Read more on docs.microsoft.com. Type: LPTSTR The buffer that will receive the text. If the string is as long or longer than the buffer, the string is truncated and terminated with a null character. Read more on docs.microsoft.com. Type: int The maximum number of characters to copy to the buffer, including the null character. If the text exceeds this limit, it is truncated. Read more on docs.microsoft.com. Type: int If the function succeeds, the return value is the length, in characters, of the copied string, not including the terminating null character. If the window has no title bar or text, if the title bar is empty, or if the window or control handle is invalid, the return value is zero. To get extended error information, call GetLastError. This function cannot retrieve the text of an edit control in another application. If the target window is owned by the current process, GetWindowText causes a WM_GETTEXT message to be sent to the specified window or control. If the target window is owned by another process and has a caption, GetWindowText retrieves the window caption text. If the window does not have a caption, the return value is a null string. This behavior is by design. It allows applications to call GetWindowText without becoming unresponsive if the process that owns the target window is not responding. However, if the target window is not responding and it belongs to the calling application, GetWindowText will cause the calling application to become unresponsive. To retrieve the text of a control in another process, send a WM_GETTEXT message directly instead of calling GetWindowText. Read more on docs.microsoft.com. Retrieves the length, in characters, of the specified window's title bar text (if the window has a title bar). (Unicode) Type: HWND A handle to the window or control. Read more on docs.microsoft.com. Type: int If the function succeeds, the return value is the length, in characters, of the text. Under certain conditions, this value might be greater than the length of the text (see Remarks). If the window has no text, the return value is zero. Function failure is indicated by a return value of zero and a GetLastError result that is nonzero. > [!NOTE] > This function does not clear the most recent error information. To determine success or failure, clear the most recent error information by calling SetLastError with 0, then call GetLastError. If the target window is owned by the current process, GetWindowTextLength causes a WM_GETTEXTLENGTH message to be sent to the specified window or control. Under certain conditions, the GetWindowTextLength function may return a value that is larger than the actual length of the text. This occurs with certain mixtures of ANSI and Unicode, and is due to the system allowing for the possible existence of double-byte character set (DBCS) characters within the text. The return value, however, will always be at least as large as the actual length of the text; you can thus always use it to guide buffer allocation. This behavior can occur when an application uses both ANSI functions and common dialogs, which use Unicode. It can also occur when an application uses the ANSI version of GetWindowTextLength with a window whose window procedure is Unicode, or the Unicode version of GetWindowTextLength with a window whose window procedure is ANSI. For more information on ANSI and ANSI functions, see Conventions for Function Prototypes. To obtain the exact length of the text, use the WM_GETTEXT, LB_GETTEXT, or CB_GETLBTEXT messages, or the GetWindowText function. > [!NOTE] > The winuser.h header defines GetWindowTextLength as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see [Conventions for Function Prototypes](/windows/win32/intl/conventions-for-function-prototypes). Read more on docs.microsoft.com. Retrieves the identifier of the thread that created the specified window and, optionally, the identifier of the process that created the window. Type: HWND A handle to the window. Read more on docs.microsoft.com. Type: LPDWORD A pointer to a variable that receives the process identifier. If this parameter is not NULL, GetWindowThreadProcessId copies the identifier of the process to the variable; otherwise, it does not. If the function fails, the value of the variable is unchanged. Read more on docs.microsoft.com. Type: DWORD If the function succeeds, the return value is the identifier of the thread that created the window. If the window handle is invalid, the return value is zero. To get extended error information, call GetLastError. Learn more about this API from docs.microsoft.com. Destroys a cursor and frees any memory the cursor occupied. Do not use this function to destroy a shared cursor. Type: HCURSOR A handle to the cursor to be destroyed. The cursor must not be in use. Read more on docs.microsoft.com. Type: BOOL If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError. The DestroyCursor function destroys a nonshared cursor. Do not use this function to destroy a shared cursor. A shared cursor is valid as long as the module from which it was loaded remains in memory. The following functions obtain a shared cursor: This doc was truncated. Read more on docs.microsoft.com. Loads the specified icon resource from the executable (.exe) file associated with an application instance. (Unicode) Type: HINSTANCE A handle to an instance of the module whose executable file contains the icon to be loaded. This parameter must be NULL when a standard icon is being loaded. Read more on docs.microsoft.com. Type: LPCTSTR The name of the icon resource to be loaded. Alternatively, this parameter can contain the resource identifier in the low-order word and zero in the high-order word. Use the MAKEINTRESOURCE macro to create this value. Read more on docs.microsoft.com. Type: HICON If the function succeeds, the return value is a handle to the newly loaded icon. If the function fails, the return value is NULL. To get extended error information, call GetLastError. LoadIcon loads the icon resource only if it has not been loaded; otherwise, it retrieves a handle to the existing resource. The function searches the icon resource for the icon most appropriate for the current display. The icon resource can be a color or monochrome bitmap. LoadIcon can only load an icon whose size conforms to the SM_CXICON and SM_CYICON system metric values. Use the LoadImage function to load icons of other sizes. > [!NOTE] > The winuser.h header defines LoadIcon as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see [Conventions for Function Prototypes](/windows/win32/intl/conventions-for-function-prototypes). Read more on docs.microsoft.com. The MapWindowPoints function converts (maps) a set of points from a coordinate space relative to one window to a coordinate space relative to another window. A handle to the window from which points are converted. If this parameter is NULL or HWND_DESKTOP, the points are presumed to be in screen coordinates. A handle to the window to which points are converted. If this parameter is NULL or HWND_DESKTOP, the points are converted to screen coordinates. A pointer to an array of POINT structures that contain the set of points to be converted. The points are in device units. This parameter can also point to a RECT structure, in which case the cPoints parameter should be set to 2. The number of POINT structures in the array pointed to by the lpPoints parameter. If the function succeeds, the low-order word of the return value is the number of pixels added to the horizontal coordinate of each source point in order to compute the horizontal coordinate of each destination point. (In addition to that, if precisely one of hWndFrom and hWndTo is mirrored, then each resulting horizontal coordinate is multiplied by -1.) The high-order word is the number of pixels added to the vertical coordinate of each source point in order to compute the vertical coordinate of each destination point. If the function fails, the return value is zero. Call SetLastError prior to calling this method to differentiate an error return value from a legitimate "0" return value. If hWndFrom or hWndTo (or both) are mirrored windows (that is, have WS_EX_LAYOUTRTL extended style) and precisely two points are passed in lpPoints, MapWindowPoints will interpret those two points as a RECT and possibly automatically swap the left and right fields of that rectangle to ensure that left is not greater than right. If any number of points other than 2 is passed in lpPoints, then MapWindowPoints will correctly map the coordinates of each of those points separately, so if you pass in a pointer to an array of more than one rectangle in lpPoints, the new rectangles may get their left field greater than right. Thus, to guarantee the correct transformation of rectangle coordinates, you must call MapWindowPoints with one RECT pointer at a time, as shown in the following example: This doc was truncated. Read more on docs.microsoft.com. The MonitorFromPoint function retrieves a handle to the display monitor that contains a specified point. A POINT structure that specifies the point of interest in virtual-screen coordinates. Determines the function's return value if the point is not contained within any display monitor. If the point is contained by a display monitor, the return value is an HMONITOR handle to that display monitor. If the point is not contained by a display monitor, the return value depends on the value of dwFlags. Learn more about this API from docs.microsoft.com. The MonitorFromRect function retrieves a handle to the display monitor that has the largest area of intersection with a specified rectangle. A pointer to a RECT structure that specifies the rectangle of interest in virtual-screen coordinates. Determines the function's return value if the rectangle does not intersect any display monitor. If the rectangle intersects one or more display monitor rectangles, the return value is an HMONITOR handle to the display monitor that has the largest area of intersection with the rectangle. If the rectangle does not intersect a display monitor, the return value depends on the value of dwFlags. Learn more about this API from docs.microsoft.com. The MonitorFromWindow function retrieves a handle to the display monitor that has the largest area of intersection with the bounding rectangle of a specified window. A handle to the window of interest. Determines the function's return value if the window does not intersect any display monitor. If the window intersects one or more display monitor rectangles, the return value is an HMONITOR handle to the display monitor that has the largest area of intersection with the window. If the window does not intersect a display monitor, the return value depends on the value of dwFlags. If the window is currently minimized, MonitorFromWindow uses the rectangle of the window before it was minimized. Dispatches incoming nonqueued messages, checks the thread message queue for a posted message, and retrieves the message (if any exist). (Unicode) Type: LPMSG A pointer to an MSG structure that receives message information. Read more on docs.microsoft.com. Type: HWND A handle to the window whose messages are to be retrieved. The window must belong to the current thread. If hWnd is NULL, PeekMessage retrieves messages for any window that belongs to the current thread, and any messages on the current thread's message queue whose hwnd value is NULL (see the MSG structure). Therefore if hWnd is NULL, both window messages and thread messages are processed. If hWnd is -1, PeekMessage retrieves only messages on the current thread's message queue whose hwnd value is NULL, that is, thread messages as posted by PostMessage (when the hWnd parameter is NULL) or PostThreadMessage. Read more on docs.microsoft.com. Type: UINT The value of the first message in the range of messages to be examined. Use WM_KEYFIRST (0x0100) to specify the first keyboard message or WM_MOUSEFIRST (0x0200) to specify the first mouse message. If wMsgFilterMin and wMsgFilterMax are both zero, PeekMessage returns all available messages (that is, no range filtering is performed). Read more on docs.microsoft.com. Type: UINT The value of the last message in the range of messages to be examined. Use WM_KEYLAST to specify the last keyboard message or WM_MOUSELAST to specify the last mouse message. If wMsgFilterMin and wMsgFilterMax are both zero, PeekMessage returns all available messages (that is, no range filtering is performed). Read more on docs.microsoft.com. Type: UINT Type: BOOL If a message is available, the return value is nonzero. If no messages are available, the return value is zero. PeekMessage retrieves messages associated with the window identified by the hWnd parameter or any of its children as specified by the IsChild function, and within the range of message values given by the wMsgFilterMin and wMsgFilterMax parameters. Note that an application can only use the low word in the wMsgFilterMin and wMsgFilterMax parameters; the high word is reserved for the system. Note that PeekMessage always retrieves WM_QUIT messages, no matter which values you specify for wMsgFilterMin and wMsgFilterMax. During this call, the system dispatches (DispatchMessage) pending, nonqueued messages, that is, messages sent to windows owned by the calling thread using the SendMessage, SendMessageCallback, SendMessageTimeout, or SendNotifyMessage function. Then the first queued message that matches the specified filter is retrieved. The system may also process internal events. If no filter is specified, messages are processed in the following order: This doc was truncated. Read more on docs.microsoft.com. Places (posts) a message in the message queue associated with the thread that created the specified window and returns without waiting for the thread to process the message. (Unicode) Type: HWND A handle to the window whose window procedure is to receive the message. The following values have special meanings. This doc was truncated. Read more on docs.microsoft.com. Type: UINT The message to be posted. For lists of the system-provided messages, see System-Defined Messages. Read more on docs.microsoft.com. Type: WPARAM Additional message-specific information. Read more on docs.microsoft.com. Type: LPARAM Additional message-specific information. Read more on docs.microsoft.com. Type: BOOL If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError. When a message is blocked by UIPI the last error, retrieved with GetLastError, is set to 5 (access denied). Messages in a message queue are retrieved by calls to the GetMessage or PeekMessage function. Applications that need to communicate using HWND_BROADCAST should use the RegisterWindowMessage function to obtain a unique message for inter-application communication. The system only does marshalling for system messages (those in the range 0 to (WM_USER-1)). To send other messages (those >= WM_USER) to another process, you must do custom marshalling. If you send a message in the range below WM_USER to the asynchronous message functions (PostMessage, SendNotifyMessage, and SendMessageCallback), its message parameters cannot include pointers. Otherwise, the operation will fail. The functions will return before the receiving thread has had a chance to process the message and the sender will free the memory before it is used. Do not post the WM_QUIT message using PostMessage; use the PostQuitMessage function. An accessibility application can use PostMessage to post WM_APPCOMMAND messages to the shell to launch applications. This functionality is not guaranteed to work for other types of applications. There is a limit of 10,000 posted messages per message queue. This limit should be sufficiently large. If your application exceeds the limit, it should be redesigned to avoid consuming so many system resources. To adjust this limit, modify the following registry key. 
HKEY_LOCAL_MACHINE SOFTWARE Microsoft Windows NT CurrentVersion Windows USERPostMessageLimit
If the function fails, call GetLastError to get extended error information. GetLastError returns ERROR_NOT_ENOUGH_QUOTA when the limit is hit. The minimum acceptable value is 4000. Read more on docs.microsoft.com. Registers a new clipboard format. This format can then be used as a valid clipboard format. (Unicode) Type: LPCTSTR The name of the new format. Read more on docs.microsoft.com. Type: UINT If the function succeeds, the return value identifies the registered clipboard format. If the function fails, the return value is zero. To get extended error information, call GetLastError. If a registered format with the specified name already exists, a new format is not registered and the return value identifies the existing format. This enables more than one application to copy and paste data using the same registered clipboard format. Note that the format name comparison is case-insensitive. Registered clipboard formats are identified by values in the range 0xC000 through 0xFFFF. When registered clipboard formats are placed on or retrieved from the clipboard, they must be in the form of an HGLOBAL value. Read more on docs.microsoft.com. The ReleaseDC function releases a device context (DC), freeing it for use by other applications. The effect of the ReleaseDC function depends on the type of DC. It frees only common and window DCs. It has no effect on class or private DCs. A handle to the window whose DC is to be released. A handle to the DC to be released. The return value indicates whether the DC was released. If the DC was released, the return value is 1. If the DC was not released, the return value is zero. The application must call the ReleaseDC function for each call to the GetWindowDC function and for each call to the GetDC function that retrieves a common DC. An application cannot use the ReleaseDC function to release a DC that was created by calling the CreateDC function; instead, it must use the DeleteDC function. ReleaseDC must be called from the same thread that called GetDC. Read more on docs.microsoft.com. Sends the specified message to a window or windows. The SendMessage function calls the window procedure for the specified window and does not return until the window procedure has processed the message. (SendMessageW) Type: HWND A handle to the window whose window procedure will receive the message. If this parameter is HWND_BROADCAST ((HWND)0xffff), the message is sent to all top-level windows in the system, including disabled or invisible unowned windows, overlapped windows, and pop-up windows; but the message is not sent to child windows. Message sending is subject to UIPI. The thread of a process can send messages only to message queues of threads in processes of lesser or equal integrity level. Read more on docs.microsoft.com. Type: UINT The message to be sent. For lists of the system-provided messages, see System-Defined Messages. Read more on docs.microsoft.com. Type: WPARAM Additional message-specific information. Read more on docs.microsoft.com. Type: LPARAM Additional message-specific information. Read more on docs.microsoft.com. Type: LRESULT The return value specifies the result of the message processing; it depends on the message sent. When a message is blocked by UIPI the last error, retrieved with GetLastError, is set to 5 (access denied). Applications that need to communicate using HWND_BROADCAST should use the RegisterWindowMessage function to obtain a unique message for inter-application communication. The system only does marshalling for system messages (those in the range 0 to (WM_USER-1)). To send other messages (those >= WM_USER) to another process, you must do custom marshalling. If the specified window was created by the calling thread, the window procedure is called immediately as a subroutine. If the specified window was created by a different thread, the system switches to that thread and calls the appropriate window procedure. Messages sent between threads are processed only when the receiving thread executes message retrieval code. The sending thread is blocked until the receiving thread processes the message. However, the sending thread will process incoming nonqueued messages while waiting for its message to be processed. To prevent this, use SendMessageTimeout with SMTO_BLOCK set. For more information on nonqueued messages, see Nonqueued Messages. An accessibility application can use SendMessage to send WM_APPCOMMAND messages to the shell to launch applications. This functionality is not guaranteed to work for other types of applications. Read more on docs.microsoft.com. Retrieves or sets the value of one of the system-wide parameters. (Unicode) Type: UINT The system-wide parameter to be retrieved or set. The possible values are organized in the following tables of related parameters: This doc was truncated. Read more on docs.microsoft.com. Type: UINT A parameter whose usage and format depends on the system parameter being queried or set. For more information about system-wide parameters, see the uiAction parameter. If not otherwise indicated, you must specify zero for this parameter. Read more on docs.microsoft.com. Type: PVOID A parameter whose usage and format depends on the system parameter being queried or set. For more information about system-wide parameters, see the uiAction parameter. If not otherwise indicated, you must specify NULL for this parameter. For information on the PVOID datatype, see Windows Data Types. Read more on docs.microsoft.com. Type: UINT If a system parameter is being set, specifies whether the user profile is to be updated, and if so, whether the WM_SETTINGCHANGE message is to be broadcast to all top-level windows to notify them of the change. Read more on docs.microsoft.com. Type: BOOL If the function succeeds, the return value is a nonzero value. If the function fails, the return value is zero. To get extended error information, call GetLastError. This function is intended for use with applications that allow the user to customize the environment. A keyboard layout name should be derived from the hexadecimal value of the language identifier corresponding to the layout. For example, U.S. English has a language identifier of 0x0409, so the primary U.S. English layout is named "00000409". Variants of U.S. English layout, such as the Dvorak layout, are named "00010409", "00020409" and so on. For a list of the primary language identifiers and sublanguage identifiers that make up a language identifier, see the MAKELANGID macro. There is a difference between the High Contrast color scheme and the High Contrast Mode. The High Contrast color scheme changes the system colors to colors that have obvious contrast; you switch to this color scheme by using the Display Options in the control panel. The High Contrast Mode, which uses SPI_GETHIGHCONTRAST and SPI_SETHIGHCONTRAST, advises applications to modify their appearance for visually-impaired users. It involves such things as audible warning to users and customized color scheme (using the Accessibility Options in the control panel). For more information, see HIGHCONTRAST. For more information on general accessibility features, see Accessibility. During the time that the primary button is held down to activate the Mouse ClickLock feature, the user can move the mouse. After the primary button is locked down, releasing the primary button does not result in a WM_LBUTTONUP message. Thus, it will appear to an application that the primary button is still down. Any subsequent button message releases the primary button, sending a WM_LBUTTONUP message to the application, thus the button can be unlocked programmatically or through the user clicking any button. This API is not DPI aware, and should not be used if the calling thread is per-monitor DPI aware. For the DPI-aware version of this API, see SystemParametersInfoForDPI. For more information on DPI awareness, see the Windows High DPI documentation. Read more on docs.microsoft.com. Retrieves the value of one of the system-wide parameters, taking into account the provided DPI value. The system-wide parameter to be retrieved. This function is only intended for use with SPI_GETICONTITLELOGFONT, SPI_GETICONMETRICS, or SPI_GETNONCLIENTMETRICS. See SystemParametersInfo for more information on these values. A parameter whose usage and format depends on the system parameter being queried. For more information about system-wide parameters, see the uiAction parameter. If not otherwise indicated, you must specify zero for this parameter. A parameter whose usage and format depends on the system parameter being queried. For more information about system-wide parameters, see the uiAction parameter. If not otherwise indicated, you must specify NULL for this parameter. For information on the PVOID datatype, see Windows Data Types. Has no effect for with this API. This parameter only has an effect if you're setting parameter. The DPI to use for scaling the metric. If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError. This function returns a similar result as SystemParametersInfo, but scales it according to an arbitrary DPI you provide (if appropriate). It only scales with the following possible values for uiAction: SPI_GETICONTITLELOGFONT, SPI_GETICONMETRICS, SPI_GETNONCLIENTMETRICS. Other possible uiAction values do not provide ForDPI behavior, and therefore this function returns 0 if called with them. For uiAction values that contain strings within their associated structures, only Unicode (LOGFONTW) strings are supported in this function. Read more on docs.microsoft.com. The WindowFromDC function returns a handle to the window associated with the specified display device context (DC). Output functions that use the specified device context draw into this window. Handle to the device context from which a handle to the associated window is to be retrieved. The return value is a handle to the window associated with the specified DC. If no window is associated with the specified DC, the return value is NULL. Learn more about this API from docs.microsoft.com. Create an interface table for the given interface. Create an interface table for the given interfaces. Create an interface table for the given interfaces. Create an interface table for the given interfaces. Create an interface table for the given interfaces. Create an interface table for the given interfaces. Create an interface table for the given interfaces. Create an interface table for the given interfaces. Returns HRESULT.STG_E_INVALIDFUNCTION as a documented way to say we don't support locking Returns HRESULT.STG_E_INVALIDFUNCTION as a documented way to say we don't support locking The CY structure is useful for calculations involving money, or for any fixed-point calculation where accuracy is particularly important. Used to flag that the COM object is a generated object. Get the specified property. Get the specified property. Get the specified property. Get the specified property. Retrieves the number of type information interfaces that an object provides (either 0 or 1). The number of type information interfaces provided by the object. If the object provides type information, this number is 1; otherwise the number is 0. This method can return one of these values. This doc was truncated. The method may return zero, which indicates that the object does not provide any type information. In this case, the object may still be programmable through IDispatch or a VTBL, but does not provide run-time type information for browsers, compilers, or other programming tools that access type information. This can be useful for hiding an object from browsers. Retrieves the type information for an object, which can then be used to get the type information for an interface. The type information to return. Pass 0 to retrieve type information for the IDispatch implementation. The locale identifier for the type information. An object may be able to return different type information for different languages. This is important for classes that support localized member names. For classes that do not support localized member names, this parameter can be ignored. The requested type information object. This method can return one of these values. This doc was truncated. Learn more about this API from docs.microsoft.com. Maps a single member and an optional set of argument names to a corresponding set of integer DISPIDs, which can be used on subsequent calls to Invoke. Reserved for future use. Must be IID_NULL. The array of names to be mapped. The count of the names to be mapped. The locale context in which to interpret the names. Caller-allocated array, each element of which contains an identifier (ID) corresponding to one of the names passed in the rgszNames array. The first element represents the member name. The subsequent elements represent each of the member's parameters. This method can return one of these values. This doc was truncated. An IDispatch implementation can associate any positive integer ID value with a given name. Zero is reserved for the default, or Value property; –1 is reserved to indicate an unknown name; and other negative values are defined for other purposes. For example, if GetIDsOfNames is called, and the implementation does not recognize one or more of the names, it returns DISP_E_UNKNOWNNAME, and the rgDispId array contains DISPID_UNKNOWN for the entries that correspond to the unknown names. The member and parameter DISPIDs must remain constant for the lifetime of the object. This allows a client to obtain the DISPIDs once, and cache them for later use. When GetIDsOfNames is called with more than one name, the first name (rgszNames[0]) corresponds to the member name, and subsequent names correspond to the names of the member's parameters. The same name may map to different DISPIDs, depending on context. For example, a name may have a DISPID when it is used as a member name with a particular interface, a different ID as a member of a different interface, and different mapping for each time it appears as a parameter. GetIDsOfNames is used when an IDispatch client binds to names at run time. To bind at compile time instead, an IDispatch client can map names to DISPIDs by using the type information interfaces described in Type Description Interfaces. This allows a client to bind to members at compile time and avoid calling GetIDsOfNames at run time. For a description of binding at compile time, see Type Description Interfaces. The implementation of GetIDsOfNames is case insensitive. Users that need case-sensitive name mapping should use type information interfaces to map names to DISPIDs, rather than call GetIDsOfNames.
Caution  You cannot use this method to access values that have been added dynamically, such as values added through JavaScript. Instead, use the GetDispID of the IDispatchEx interface. For more information, see the IDispatchEx interface.
 
 Read more on docs.microsoft.com. Provides access to properties and methods exposed by an object. Identifies the member. Use GetIDsOfNames or the object's documentation to obtain the dispatch identifier. Reserved for future use. Must be IID_NULL. The locale context in which to interpret arguments. The lcid is used by the GetIDsOfNames function, and is also passed to Invoke to allow the object to interpret its arguments specific to a locale. Applications that do not support multiple national languages can ignore this parameter. For more information, refer to Supporting Multiple National Languages and Exposing ActiveX Objects. Read more on docs.microsoft.com. Flags describing the context of the Invoke call. This doc was truncated. Read more on docs.microsoft.com. Pointer to a DISPPARAMS structure containing an array of arguments, an array of argument DISPIDs for named arguments, and counts for the number of elements in the arrays. Pointer to the location where the result is to be stored, or NULL if the caller expects no result. This argument is ignored if DISPATCH_PROPERTYPUT or DISPATCH_PROPERTYPUTREF is specified. Pointer to a structure that contains exception information. This structure should be filled in if DISP_E_EXCEPTION is returned. Can be NULL. The index within rgvarg of the first argument that has an error. Arguments are stored in pDispParams->rgvarg in reverse order, so the first argument is the one with the highest index in the array. This parameter is returned only when the resulting return value is DISP_E_TYPEMISMATCH or DISP_E_PARAMNOTFOUND. This argument can be set to null. For details, see Returning Errors. This method can return one of these values. This doc was truncated. Generally, you should not implement Invoke directly. Instead, use the dispatch interface to create functions CreateStdDispatch and DispInvoke. For details, refer to CreateStdDispatch, DispInvoke, Creating the IDispatch Interface and Exposing ActiveX Objects. If some application-specific processing needs to be performed before calling a member, the code should perform the necessary actions, and then call ITypeInfo::Invoke to invoke the member. ITypeInfo::Invoke acts exactly like Invoke. The standard implementations of Invoke created by CreateStdDispatch and DispInvoke defer to ITypeInfo::Invoke. In an ActiveX client, Invoke should be used to get and set the values of properties, or to call a method of an ActiveX object. The dispIdMember argument identifies the member to invoke. The DISPIDs that identify members are defined by the implementer of the object and can be determined by using the object's documentation, the IDispatch::GetIDsOfNames function, or the ITypeInfo interface. When you use IDispatch::Invoke() with DISPATCH_PROPERTYPUT or DISPATCH_PROPERTYPUTREF, you have to specially initialize the cNamedArgs and rgdispidNamedArgs elements of your DISPPARAMS structure with the following: This doc was truncated. Read more on docs.microsoft.com. The IID guid for this interface. {00020400-0000-0000-c000-000000000046} An interface that provides a COM callable wrapper for the implementing class. The implementing class should not be public and unsealed as it can be derived from and COM interfaces can be added. This is meant to be a fixed set of interfaces. NET CCWs generated by built-in COM interop always support IMarshal, ISupportErrorInfo, IDispatchEx, IProvideClassInfo, and IConnectionPointContainer. They also usually expose IAgileObject. On Exception objects the CCW also supports IErrorInfo. These must explicitly be provided with this mechanism. .NET Framework also supported the following interfaces, which are not implemented on .NET Core: IManagedObject - used .NET Remoting (not available on .NET Core) IObjectSafety - for Code Access Security (not available on .NET Core) IWeakReferenceSource - for WinRT ICustomPropertyProvider - for WinRT XAML (Jupiter) IReferenceTrackerTarget - for WinRT IStringable - for WinRT Apply to a class to apply a COM callable wrapper of the given . The class must also derive from the given COM wrapper 's nested Interface. Apply to a class to apply a COM callable wrapper of the given and . The class must also derive from both of the given COM wrapper 's nested Interface. Apply to a class to apply a COM callable wrapper of the given interfaces. The class must also derive from the given COM wrapper structs' nested Interfaces. Apply to a class to apply a COM callable wrapper of the given interfaces. The class must also derive from the given COM wrapper structs' nested Interfaces. Apply to a class to apply a COM callable wrapper of the given interfaces. The class must also derive from the given COM wrapper structs' nested Interfaces. Apply to a class to apply a COM callable wrapper of the given interfaces. The class must also derive from the given COM wrapper structs' nested Interfaces. Apply to a class to apply a COM callable wrapper of the given interfaces. The class must also derive from the given COM wrapper structs' nested Interfaces. Apply to a class to apply a COM callable wrapper of the given interfaces. The class must also derive from the given COM wrapper structs' nested Interfaces. Retrieves a TYPEATTR structure that contains the attributes of the type description. The attributes of this type description. This method can return one of these values. This doc was truncated. To free the TYPEATTR structure, use ITypeInfo::ReleaseTypeAttr. Retrieves the ITypeComp interface for the type description, which enables a client compiler to bind to the type description's members. The ITypeComp of the containing type library. This method can return one of these values. This doc was truncated. A client compiler can use the ITypeComp interface to bind to members of the type. Retrieves the FUNCDESC structure that contains information about a specified function. The index of the function whose description is to be returned. The index should be in the range of 0 to 1 less than the number of functions in this type. A FUNCDESC structure that describes the specified function. This method can return one of these values. This doc was truncated. The function ITypeInfo::GetFuncDesc provides access to a FUNCDESC structure that describes the function with the specified index. The FUNCDESC structure should be freed with ITypeInfo::ReleaseFuncDesc. The number of functions in the type is one of the attributes contained in the TYPEATTR structure. Retrieves a VARDESC structure that describes the specified variable. The index of the variable whose description is to be returned. The index should be in the range of 0 to 1 less than the number of variables in this type. A VARDESC that describes the specified variable. This method can return one of these values. This doc was truncated. To free the VARDESC structure, use ReleaseVarDesc. Retrieves the variable with the specified member ID or the name of the property or method and the parameters that correspond to the specified function ID. The ID of the member whose name (or names) is to be returned. The caller-allocated array. On return, each of the elements contains the name (or names) associated with the member. The length of the passed-in rgBstrNames array. The number of names in the rgBstrNames array. This method can return one of these values. This doc was truncated. The caller must release the returned BSTR array. If the member ID identifies a property that is implemented with property functions, the property name is returned. For property get functions, the names of the function and its parameters are always returned. For property put and put reference functions, the right side of the assignment is unnamed. If cMaxNames is less than is required to return all of the names of the parameters of a function, then only the names of the first cMaxNames - 1 parameters are returned. The names of the parameters are returned in the array in the same order that they appear elsewhere in the interface (for example, the same order in the parameter array associated with the FUNCDESC enumeration). If the type description inherits from another type description, this function is recursive to the base type description, if necessary, to find the item with the requested member ID. Read more on docs.microsoft.com. If a type description describes a COM class, it retrieves the type description of the implemented interface types. The index of the implemented type whose handle is returned. The valid range is 0 to the cImplTypes field in the TYPEATTR structure. A handle for the implemented interface (if any). This handle can be passed to ITypeInfo::GetRefTypeInfo to get the type description. This method can return one of these values. This doc was truncated. If the TKIND_DISPATCH type description is for a dual interface, the TKIND_INTERFACE type description can be obtained by calling GetRefTypeOfImplType with an index of –1, and by passing the returned pRefTypehandle to GetRefTypeInfo to retrieve the type information. Retrieves the IMPLTYPEFLAGS enumeration for one implemented interface or base interface in a type description. The index of the implemented interface or base interface for which to get the flags. The IMPLTYPEFLAGS enumeration value. This method can return one of these values. This doc was truncated. The flags are associated with the act of inheritance, and not with the inherited interface. Maps between member names and member IDs, and parameter names and parameter IDs. An array of names to be mapped. The count of the names to be mapped. Caller-allocated array in which name mappings are placed. This method can return one of these values. This doc was truncated. The function GetIDsOfNames maps the name of a member (rgszNames[0]) and its parameters (rgszNames[1] ...rgszNames[cNames- 1]) to the ID of the member (pMemId[0]), and to the IDs of the specified parameters (pMemId[1] ... pMemId[cNames- 1]). The IDs of parameters are 0 for the first parameter in the member function's argument list, 1 for the second, and so on. If the type description inherits from another type description, this function is recursive to the base type description, if necessary, to find the item with the requested member ID. Read more on docs.microsoft.com. Invokes a method, or accesses a property of an object, that implements the interface described by the type description. An instance of the interface described by this type description. The interface member. Flags describing the context of the invoke call. This doc was truncated. Read more on docs.microsoft.com. An array of arguments, an array of DISPIDs for named arguments, and counts of the number of elements in each array. The result. Should be null if the caller does not expect any result. If wFlags specifies DISPATCH_PROPERTYPUT or DISPATCH_PROPERTYPUTREF, pVarResultis is ignored. An exception information structure, which is filled in only if DISP_E_EXCEPTION is returned. If pExcepInfo is null on input, only an HRESULT error will be returned. If Invoke returns DISP_E_TYPEMISMATCH, puArgErr indicates the index (within rgvarg) of the argument with incorrect type. If more than one argument returns an error, puArgErr indicates only the first argument with an error. Arguments in pDispParams->rgvarg appear in reverse order, so the first argument is the one having the highest index in the array. This parameter cannot be null. This doc was truncated. Use the function ITypeInfo::Invoke to access a member of an object or invoke a method that implements the interface described by this type description. For objects that support the IDispatch interface, you can use Invoke to implement IDispatch::Invoke. ITypeInfo::Invoke takes a pointer to an instance of the class. Otherwise, its parameters are the same as IDispatch::Invoke, except that ITypeInfo::Invoke omits the refiid and lcid parameters. When called, ITypeInfo::Invoke performs the actions described by the IDispatch::Invoke parameters on the specified instance. For VTBL interface members, ITypeInfo::Invoke passes the LCID of the type information into parameters tagged with the lcid attribute, and the returned value into the retval attribute. If the type description inherits from another type description, this function recurses on the base type description to find the item with the requested member ID. Read more on docs.microsoft.com. Retrieves the documentation string, the complete Help file name and path, and the context ID for the Help topic for a specified type description. The ID of the member whose documentation is to be returned. The name of the specified item. If the caller does not need the item name, pBstrName can be null. The documentation string for the specified item. If the caller does not need the documentation string, pBstrDocString can be null. The Help localization context. If the caller does not need the Help context, it can be null. The fully qualified name of the file containing the DLL used for Help file. If the caller does not need the file name, it can be null. This method can return one of these values. This doc was truncated. The function GetDocumentation provides access to the documentation for the member specified by the memid parameter. If the passed-in memid is MEMBERID_NIL, then the documentation for the type description is returned. If the type description inherits from another type description, this function is recursive to the base type description, if necessary, to find the item with the requested member ID. The caller should use SysFreeString to free the BSTRs referenced by pBstrName, pBstrDocString, and pBstrHelpFile. Read more on docs.microsoft.com. Retrieves a description or specification of an entry point for a function in a DLL. The ID of the member function whose DLL entry description is to be returned. The kind of member identified by memid. This is important for properties, because one memid can identify up to three separate functions. If not null, the function sets pBstrDllName to the name of the DLL. If not null, the function sets pBstrName to the name of the entry point. If the entry point is specified by an ordinal, this argument is null. If not null, and if the function is defined by an ordinal, the function sets pwOrdinal to the ordinal. This method can return one of these values. This doc was truncated. The caller passes in a member ID, which represents the member function whose entry description is desired. If the function has a DLL entry point, the name of the DLL that contains the function, as well as its name or ordinal identifier, are placed in the passed-in pointers allocated by the caller. If there is no DLL entry point for the function, an error is returned. If the type description inherits from another type description, this function is recursive to the base type description, if necessary, to find the item with the requested member ID. The caller should use SysFreeString to free the BSTRs referenced by pBstrName and pBstrDllName. Read more on docs.microsoft.com. If a type description references other type descriptions, it retrieves the referenced type descriptions. A handle to the referenced type description to return. The referenced type description. This method can return one of these values. This doc was truncated. On return, the second parameter contains a pointer to a pointer to a type description that is referenced by this type description. A type description must have a reference to each type description that occurs as the type of any of its variables, function parameters, or function return types. For example, if the type of a data member is a record type, the type description for that data member contains the hRefType of a referenced type description. To get a pointer to the type description, the reference is passed to GetRefTypeInfo. Retrieves the addresses of static functions or variables, such as those defined in a DLL. The member ID of the static member whose address is to be retrieved. The member ID is defined by the DISPID. Indicates whether the member is a property, and if so, what kind. The static member. This method can return one of these values. This doc was truncated. The addresses are valid until the caller releases its reference to the type description. The invKind parameter can be ignored unless the address of a property function is being requested. If the type description inherits from another type description, this function is recursive to the base type description, if necessary, to find the item with the requested member ID. Read more on docs.microsoft.com. Creates a new instance of a type that describes a component object class (coclass). The controlling IUnknown. If Null, then a stand-alone instance is created. If valid, then an aggregate object is created. An ID for the interface that the caller will use to communicate with the resulting object. An instance of the created object. This doc was truncated. For types that describe a component object class (coclass), CreateInstance creates a new instance of the class. Normally, CreateInstance calls CoCreateInstance with the type description's GUID. For an Application object, it first calls GetActiveObject. If the application is active, GetActiveObject returns the active object; otherwise, if GetActiveObject fails, CreateInstance calls CoCreateInstance. Retrieves marshaling information. The member ID that indicates which marshaling information is needed. The opcode string used in marshaling the fields of the structure described by the referenced type description, or null if there is no information to return. This method can return one of these values. This doc was truncated. If the passed-in member ID is MEMBERID_NIL, the function returns the opcode string for marshaling the fields of the structure described by the type description. Otherwise, it returns the opcode string for marshaling the function specified by the index. If the type description inherits from another type description, this function recurses on the base type description, if necessary, to find the item with the requested member ID. Read more on docs.microsoft.com. Retrieves the containing type library and the index of the type description within that type library. The containing type library. The index of the type description within the containing type library. This method can return one of these values. This doc was truncated. Learn more about this API from docs.microsoft.com. Releases a TYPEATTR previously returned by ITypeInfo::GetTypeAttr. The TYPEATTR to be freed. Learn more about this API from docs.microsoft.com. Releases a FUNCDESC previously returned by ITypeInfo::GetFuncDesc. The FUNCDESC to be freed. Learn more about this API from docs.microsoft.com. Releases a VARDESC previously returned by ITypeInfo::GetVarDesc. The VARDESC to be freed. Learn more about this API from docs.microsoft.com. The IID guid for this interface. {00020401-0000-0000-c000-000000000046} Manual COM Callable Wrapper for . This is for test and debug scenarios only. It should not be used directly in the product. This is a simplified version of what does. It is useful when we want to manage our own handling for debugging and testing purposes. Creates a manual COM Callable Wrapper for the given . Increments the reference count for an interface pointer to a COM object. You should call this method whenever you make a copy of an interface pointer. The method returns the new reference count. This value is intended to be used only for test purposes. A COM object uses a per-interface reference-counting mechanism to ensure that the object doesn't outlive references to it. You use **AddRef** to stabilize a copy of an interface pointer. It can also be called when the life of a cloned pointer must extend beyond the lifetime of the original pointer. The cloned pointer must be released by calling [IUnknown::Release](/windows/desktop/api/unknwn/nf-unknwn-iunknown-queryinterface(refiid_void)) on it. The internal reference counter that **AddRef** maintains should be a 32-bit unsigned integer. Read more on docs.microsoft.com. Decrements the reference count for an interface on a COM object. The method returns the new reference count. This value is intended to be used only for test purposes. When the reference count on an object reaches zero, **Release** must cause the interface pointer to free itself. When the released pointer is the only (formerly) outstanding reference to an object (whether the object supports single or multiple interfaces), the implementation must free the object. Note that aggregation of objects restricts the ability to recover interface pointers. Read more on docs.microsoft.com. The IID guid for this interface. {00000000-0000-0000-c000-000000000046} Struct that handles managed object COM projection lifetime management. Struct that repesents the VTable for a COM pointer. The type of object being projected. Allocate a lifetime wrapper for the given with the given . This creates a to root the until ref counting has gone to zero. The should be fixed, typically as a static. Com calls always include the "this" pointer as the first argument. Get the object associated with this lifetime. The passed back "this" pointer that originally came from . The object associated with this lifetime, if any. The handle was freed. Represents a safe array. The array rgsabound is stored with the left-most dimension in rgsabound[0] and the right-most dimension in rgsabound[cDims - 1]. If an array was specified in a C-like syntax as a [2][5], it would have two elements in the rgsabound vector. Element 0 has an lLbound of 0 and a cElements of 2. Element 1 has an lLbound of 0 and a cElements of 5. The fFeatures flags describe attributes of an array that can affect how the array is released. The fFeatures field describes what type of data is stored in the SAFEARRAY and how the array is allocated. This allows freeing the array without referencing its containing variant. Read more on docs.microsoft.com. Gets the of the . Creates an empty one-dimensional SAFEARRAY of type . The number of dimensions. Flags. This doc was truncated. Read more on docs.microsoft.com. The size of an array element. The number of times the array has been locked without a corresponding unlock. The data. One bound for each dimension. Computes the amount of memory that must be allocated to store this struct, including the specified number of elements in the variable length inline array at the end. Helper to scope lifetime of a created via Destroys the (if any) when disposed. Note that this scope currently only works for a one dimensional . Use in a statement to ensure the gets disposed. If the you are intending to scope the lifetime of has type , use for better usability. A copy will be made of anything that is put into the and anything the gives out is a copy and has been add ref appropriately if applicable. Be sure to dispose of items that are given to the if necessary. All items given out by the should be disposed. Untyped representation of CA* typed arrays in Windows. , etc. Retrieves a specified number of STATSTG structures, that follow in the enumeration sequence. The number of STATSTG structures requested. An array of STATSTG structures returned. The number of STATSTG structures retrieved in the rgelt parameter. This method supports the following return values: This doc was truncated. Learn more about this API from docs.microsoft.com. Skips a specified number of STATSTG structures in the enumeration sequence. The number of STATSTG structures to skip. This method supports the following return values: | Return code | Description | |----------------|---------------| | S_OK | The specified number of **STATSTG** structures that were successfully skipped. | | S_FALSE | The number of **STATSTG** structures skipped is less than the *celt* parameter. | Learn more about this API from docs.microsoft.com. Resets the enumeration sequence to the beginning of the STATSTG structure array. This method supports the S_OK return value. This doc was truncated. Learn more about this API from docs.microsoft.com. Creates a new enumerator that contains the same enumeration state as the current STATSTG structure enumerator. A pointer to the variable that receives the IEnumSTATSTG interface pointer. If the method is unsuccessful, the value of the ppenum parameter is undefined. Read more on docs.microsoft.com. This method supports the following return values. This doc was truncated. Learn more about this API from docs.microsoft.com. The IID guid for this interface. {0000000d-0000-0000-c000-000000000046} Creates and opens a stream object with the specified name contained in this storage object. A pointer to a wide character null-terminated Unicode string that contains the name of the newly created stream. The name can be used later to open or reopen the stream. The name must not exceed 31 characters in length, not including the string terminator. The 000 through 01f characters, serving as the first character of the stream/storage name, are reserved for use by OLE. This is a compound file restriction, not a structured storage restriction. Specifies the access mode to use when opening the newly created stream. For more information and descriptions of the possible values, see STGM Constants. Reserved for future use; must be zero. Reserved for future use; must be zero. On return, pointer to the location of the new IStream interface pointer. This is only valid if the operation is successful. When an error occurs, this parameter is set to NULL. Read more on docs.microsoft.com. This method can return one of these values. | Return code | Description | |----------------|---------------| |S_OK | The new stream was successfully created.| |E_PENDING | Asynchronous Storage only: Part or all of the necessary data is currently unavailable. | |STG_E_ACCESSDENIED | Not enough permissions to create stream.| |STG_E_FILEALREADYEXISTS | The name specified for the stream already exists in the storage object and the *grfMode* parameter includes the value STGM_FAILIFTHERE.| |STG_E_INSUFFICIENTMEMORY | The stream was not created due to a lack of memory.| |STG_E_INVALIDFLAG | The value specified for the *grfMode* parameter is not a valid **STGM** constants value.| |STG_E_INVALIDFUNCTION | The specified combination of flags in the *grfMode* parameter is not supported; for example, when this method is called without the STGM_SHARE_EXCLUSIVE flag.| |STG_E_INVALIDNAME | Invalid value for *pwcsName*.| |STG_E_INVALIDPOINTER | The pointer specified for the stream object was invalid.| |STG_E_INVALIDPARAMETER | One of the parameters was invalid.| |STG_E_REVERTED | The storage object has been invalidated by a revert operation above it in the transaction tree.| |STG_E_TOOMANYOPENFILES | The stream was not created because there are too many open files.| If a stream with the name specified in the pwcsName parameter already exists and the grfMode parameter includes the STGM_CREATE flag, the existing stream is replaced by a newly created one. Both the destruction of the old stream and the creation of the new stream object are subject to the transaction mode on the parent storage object. The COM-provided compound file implementation of the IStorage::CreateStream method does not support the following behaviors: This doc was truncated. Read more on docs.microsoft.com. Opens an existing stream object within this storage object in the specified access mode. A pointer to a wide character null-terminated Unicode string that contains the name of the stream to open. The 000 through 01f characters, serving as the first character of the stream/storage name, are reserved for use by OLE. This is a compound file restriction, not a structured storage restriction. Reserved for future use; must be NULL. Specifies the access mode to be assigned to the open stream. For more information and descriptions of possible values, see STGM Constants. Other modes you choose must at least specify STGM_SHARE_EXCLUSIVE when calling this method in the compound file implementation. Reserved for future use; must be zero. A pointer to IStream pointer variable that receives the interface pointer to the newly opened stream object. If an error occurs, *ppstm must be set to NULL. Read more on docs.microsoft.com. This method can return one of these values. | Return code | Description | |----------------|---------------| |S_OK | The stream was successfully opened.| |E_PENDING | Asynchronous Storage only: Part or all of the stream data is currently unavailable. | |STG_E_ACCESSDENIED | Not enough permissions to open stream.| |STG_E_FILENOTFOUND | The stream with specified name does not exist.| |STG_E_INSUFFICIENTMEMORY | The stream was not opened due to a lack of memory.| |STG_E_INVALIDFLAG | The value specified for the *grfMode* parameter is not a valid **STGM** constants value.| |STG_E_INVALIDFUNCTION | The specified combination of flags in the *grfMode* parameter is not supported; for example, when this method is called without the STGM_SHARE_EXCLUSIVE flag.| |STG_E_INVALIDNAME | Invalid value for *pwcsName*.| |STG_E_INVALIDPOINTER | The pointer specified for the stream object was not valid.| |STG_E_INVALIDPARAMETER | One of the parameters was not valid.| |STG_E_REVERTED | The storage object has been invalidated by a revert operation above it in the transaction tree.| |STG_E_TOOMANYOPENFILES | The stream was not opened because there are too many open files.| IStorage::OpenStream opens an existing stream object within this storage object in the access mode specified in grfMode. There are restrictions on the permissions that can be given in grfMode. For example, the permissions on this storage object restrict the permissions on its streams. In general, access restrictions on streams need to be stricter than those on their parent storages. Compound-file streams must be opened with STGM_SHARE_EXCLUSIVE. Opens an existing storage object with the specified name in the specified access mode. A pointer to a wide character null-terminated Unicode string that contains the name of the storage object to open. The 000 through 01f characters, serving as the first character of the stream/storage name, are reserved for use by OLE. This is a compound file restriction, not a structured storage restriction. It is ignored if pstgPriority is non-NULL. Must be NULL. A non-NULL value will return STG_E_INVALIDPARAMETER. Specifies the access mode to use when opening the storage object. For descriptions of the possible values, see STGM Constants. Other modes you choose must at least specify STGM_SHARE_EXCLUSIVE when calling this method. Must be NULL. A non-NULL value will return STG_E_INVALIDPARAMETER. Reserved for future use; must be zero. When successful, pointer to the location of an IStorage pointer to the opened storage object. This parameter is set to NULL if an error occurs. Read more on docs.microsoft.com. This method can return one of these values. | Return code | Description | |----------------|---------------| |S_OK | The storage object was opened successfully.| |E_PENDING | Asynchronous Storage only: Part or all of the storage's data is currently unavailable. | |STG_E_ACCESSDENIED | Not enough permissions to open storage object.| |STG_E_FILENOTFOUND | The storage object with the specified name does not exist.| |STG_E_INSUFFICIENTMEMORY | The storage object was not opened due to a lack of memory.| |STG_E_INVALIDFLAG | The value specified for the *grfMode* parameter is not a valid **STGM** constants value.| |STG_E_INVALIDFUNCTION | The specified combination of flags in the *grfMode* parameter is not supported.| |STG_E_INVALIDNAME | Not a valid value for *pwcsName*.| |STG_E_INVALIDPOINTER | The pointer specified for the storage object was not valid.| |STG_E_INVALIDPARAMETER | One of the parameters was not valid.| |STG_E_REVERTED | The storage object has been invalidated by a revert operation above it in the transaction tree.| |STG_E_TOOMANYOPENFILES | The storage object was not created because there are too many open files.| |STG_S_CONVERTED | The existing stream with the specified name was replaced with a new storage object containing a single stream called CONTENTS. In direct mode, the new storage is immediately written to disk. In transacted mode, the new storage is written to a temporary storage in memory and later written to disk when it is committed.| If the pstgPriority parameter is NULL, it is ignored. If the pstgPriority parameter is not NULL, it is an IStorage pointer to a previous opening of an element of the storage object, usually one that was opened in priority mode. The storage object should be closed and reopened according to grfMode. When the IStorage::OpenStorage method returns, pstgPriority is no longer valid. Use the value supplied in the ppstg parameter. Storage objects can be opened with STGM_DELETEONRELEASE, in which case the object is destroyed when it receives its final release. This is useful for creating temporary storage objects. Read more on docs.microsoft.com. Copies the entire contents of an open storage object to another storage object. The number of elements in the array pointed to by rgiidExclude. If rgiidExclude is NULL, then ciidExclude is ignored. An array of interface identifiers (IIDs) that either the caller knows about and does not want copied or that the storage object does not support, but whose state the caller will later explicitly copy. The array can include IStorage, indicating that only stream objects are to be copied, and IStream, indicating that only storage objects are to be copied. An array length of zero indicates that only the state exposed by the IStorage object is to be copied; all other interfaces on the object are to be ignored. Passing NULL indicates that all interfaces on the object are to be copied. Read more on docs.microsoft.com. A string name block (refer to SNB) that specifies a block of storage or stream objects that are not to be copied to the destination. These elements are not created at the destination. If IID_IStorage is in the rgiidExclude array, this parameter is ignored. This parameter may be NULL. Read more on docs.microsoft.com. A pointer to the open storage object into which this storage object is to be copied. The destination storage object can be a different implementation of the IStorage interface from the source storage object. Thus, IStorage::CopyTo can use only publicly available methods of the destination storage object. If pstgDest is open in transacted mode, it can be reverted by calling its IStorage::Revert method. Read more on docs.microsoft.com. This method can return one of these values. | Return code | Description | |----------------|---------------| |S_OK | The storage object was successfully copied.| |E_PENDING | Asynchronous Storage only: Part or all of the data to be copied is currently unavailable. | |STG_E_ACCESSDENIED | The destination storage object is a child of the source storage object.| |STG_E_INSUFFICIENTMEMORY | The copy was not completed due to a lack of memory.| |STG_E_INVALIDPOINTER | The pointer specified for the storage object was not valid.| |STG_E_INVALIDPARAMETER | One of the parameters was not valid.| |STG_E_TOOMANYOPENFILES | The copy was not completed because there are too many open files.| |STG_E_REVERTED | The storage object has been invalidated by a revert operation above it in the transaction tree.| |STG_E_MEDIUMFULL | The copy was not completed because the storage medium is full.| This method merges elements contained in the source storage object with those already present in the destination. The layout of the destination storage object may differ from the source storage object. The copy process is recursive, invoking IStorage::CopyTo and IStream::CopyTo on the elements nested inside the source. When copying a stream on top of an existing stream with the same name, the existing stream is first removed and then replaced with the source stream. When copying a storage on top of an existing storage with the same name, the existing storage is not removed. As a result, after the copy operation, the destination IStorage contains older elements, unless they were replaced by newer ones with the same names. A storage object may expose interfaces other than IStorage, including IRootStorage, IPropertyStorage, or IPropertySetStorage. The rgiidExclude parameter permits the exclusion of any or all of these additional interfaces from the copy operation. A caller with a newer or more efficient copy of an existing substorage or stream object may want to exclude the current versions of these objects from the copy operation. The snbExclude and rgiidExclude parameters provide two ways of excluding a storage objects existing storages or streams.

Note to Callers

The most common way to use the IStorage::CopyTo method is to copy everything from the source to the destination, as in most full-save and save-as operations. The following example code shows how to copy everything from the source storage object to the destination storage object. This doc was truncated. Read more on docs.microsoft.com. The MoveElementTo method copies or moves a substorage or stream from this storage object to another storage object. Pointer to a wide character null-terminated Unicode string that contains the name of the element in this storage object to be moved or copied. IStorage pointer to the destination storage object. Pointer to a wide character null-terminated unicode string that contains the new name for the element in its new storage object. Specifies whether the operation should be a move (STGMOVE_MOVE) or a copy (STGMOVE_COPY). See the STGMOVE enumeration. Read more on docs.microsoft.com. This method can return one of these values. | Return code | Description | |----------------|---------------| |S_OK | The storage object was successfully copied or moved.| |E_PENDING | Asynchronous Storage only: Part or all of the element's data is currently unavailable. | |STG_E_ACCESSDENIED | The destination storage object is a child of the source storage object. Or, the destination object and element name are the same as the source object and element name. In other words, you cannot move an element to itself.| |STG_E_FILENOTFOUND | The element with the specified name does not exist.| |STG_E_FILEALREADYEXISTS | The specified file already exists.| |STG_E_INSUFFICIENTMEMORY | The copy or move was not completed due to a lack of memory.| |STG_E_INVALIDFLAG | The value for the *grfFlags* parameter is not valid.| |STG_E_INVALIDNAME | Not a valid value for *pwcsName*.| |STG_E_INVALIDPOINTER | The pointer specified for the storage object was not valid.| |STG_E_INVALIDPARAMETER | One of the parameters was not valid.| |STG_E_REVERTED | The storage object has been invalidated by a revert operation above it in the transaction tree.| |STG_E_TOOMANYOPENFILES | The copy or move was not completed because there are too many open files.| The IStorage::MoveElementTo method is typically the same as invoking the IStorage::CopyTo method on the indicated element and then removing the source element. In this case, the MoveElementTo method uses only the publicly available functions of the destination storage object to carry out the move. If the source and destination storage objects have special knowledge about each other's implementation (they could, for example, be different instances of the same implementation), this method can be implemented more efficiently. Before calling this method, the element to be moved must be closed, and the destination storage must be open. Also, the destination object and element cannot be the same storage object/element name as the source of the move. That is, you cannot move an element to itself. Read more on docs.microsoft.com. The Commit method ensures that any changes made to a storage object open in transacted mode are reflected in the parent storage. Controls how the changes are committed to the storage object. See the STGC enumeration for a definition of these values. Read more on docs.microsoft.com. This method can return one of these values. | Return code | Description | |----------------|---------------| |S_OK | Changes to the storage object were successfully committed to the parent level. If STGC_CONSOLIDATE was specified, the storage was successfully consolidated, or the storage was already too compact to consolidate further.| |STG_S_MULTIPLEOPENS | The commit operation succeeded, but the storage could not be consolidated because it had been opened multiple times using the STGM_NOSNAPSHOT flag.| |STG_S_CANNOTCONSOLIDATE | The commit operation succeeded, but the storage could not be consolidated due to an incorrect storage mode. For compound files, the storage may have been opened using the STGM_NOSCRATCH flag, or the storage may not be the outermost transacted level.| |STG_S_CONSOLIDATIONFAILED | The commit operation succeeded, but the storage could not be consolidated due to an internal error (for example, a memory allocation failure).| |E_PENDING | Asynchronous storage only: Part or all of the data to be committed is currently unavailable.| |STG_E_INVALIDFLAG | The value for the *grfCommitFlags* parameter is not valid.| |STG_E_INVALIDPARAMETER | One of the parameters was not valid.| |STG_E_NOTCURRENT | Another open instance of the storage object has committed changes. As a result, the current commit operation may overwrite previous changes.| |STG_E_MEDIUMFULL | No space left on device to commit.| |STG_E_TOOMANYOPENFILES | The commit operation could not be completed because there are too many open files.| |STG_E_REVERTED | The storage object has been invalidated by a revert operation above it in the transaction tree.| IStorage::Commit makes permanent changes to a storage object that is in transacted mode, in which changes are accumulated in a buffer, and not reflected in the storage object until there is a call to this method. The alternative is to open an object in direct mode, in which changes are immediately reflected in the storage object. An object opened in the direct mode does not require calling IStorage::Commit to make permanent changes in the storage object. Calling the IStorage::Commit method on a nonroot storage opened in direct mode has no effect. Opening a root storage object in direct mode ensures that changes in memory buffers are written to the underlying storage device. The commit operation publishes the current changes in this storage object and its children to the next level up in the storage hierarchy. To undo current changes before committing them, call IStorage::Revert to roll back to the last-committed version. Calling IStorage::Commit has no effect on currently opened nested elements of this storage object. They remain valid and can be used. However, the IStorage::Commit method does not automatically commit changes to these nested elements. The commit operation publishes only known changes to the next higher level in the storage hierarchy. Thus, transactions to nested levels must be committed to this storage object before they can be committed to higher levels. In commit operations, you need to take steps to ensure that data is protected during the commit process: This doc was truncated. Read more on docs.microsoft.com. The Revert method discards all changes that have been made to the storage object since the last commit operation. This method can return one of these values. | Return code | Description | |----------------|---------------| |S_OK | The revert operation was successful.| |E_PENDING | Asynchronous Storage only: Part or all of the storage's data is currently unavailable. | |STG_E_INSUFFICIENTMEMORY | The revert operation could not be completed due to a lack of memory.| |STG_E_TOOMANYOPENFILES | The revert operation could not be completed because there are too many open files.| |STG_E_REVERTED | The storage object has been invalidated by a revert operation above it in the transaction tree.| For storage objects opened in transacted mode, the IStorage::Revert method discards any uncommitted changes to this storage object or changes that have been committed to this storage object from nested elements. After this method returns, any existing elements (substorages or streams) that were opened from the reverted storage object are invalid and can no longer be used. Specifying these reverted elements in any call except IUnknown::Release returns the error STG_E_REVERTED This method has no effect on storage objects opened in direct mode. Read more on docs.microsoft.com. The EnumElements method retrieves a pointer to an enumerator object that can be used to enumerate the storage and stream objects contained within this storage object. Reserved for future use; must be zero. Reserved for future use; must be NULL. Reserved for future use; must be zero. Pointer to IEnumSTATSTG* pointer variable that receives the interface pointer to the new enumerator object. Read more on docs.microsoft.com. This method can return one of these values. | Return code | Description | |----------------|---------------| |S_OK | The enumerator object was successfully returned.| |E_PENDING | Asynchronous Storage only: Part or all of the element's data is currently unavailable.| |STG_E_INSUFFICIENTMEMORY | The enumerator object could not be created due to lack of memory.| |STG_E_INVALIDPARAMETER | One of the parameters was not valid.| |STG_E_REVERTED | The storage object has been invalidated by a revert operation above it in the transaction tree.| The enumerator object returned by this method implements the IEnumSTATSTG interface, one of the standard enumerator interfaces that contain the Next, Reset, Clone, and Skip methods. IEnumSTATSTG enumerates the data stored in an array of STATSTG structures. The storage object must be open in read mode to allow the enumeration of its elements. The enumerator object is permitted to enumerate the elements in any order. The enumerator object is also permitted to treat the enumeration as a snapshot or to have the enumeration reflect the current state of the storage object. Read more on docs.microsoft.com. The RenameElement method renames the specified substorage or stream in this storage object. Pointer to a wide character null-terminated Unicode string that contains the name of the substorage or stream to be changed.
Note  The pwcsName, created in CreateStorage or CreateStream must not exceed 31 characters in length, not including the string terminator.
 
 Read more on docs.microsoft.com. Pointer to a wide character null-terminated unicode string that contains the new name for the specified substorage or stream.
Note  The pwcsName, created in CreateStorage or CreateStream must not exceed 31 characters in length, not including the string terminator.
 
 Read more on docs.microsoft.com. This method can return one of these values. | Return code | Description | |----------------|---------------| |S_OK | The element was successfully renamed.| |E_PENDING | Asynchronous Storage only: Part or all of the element's data is currently unavailable.| |STG_E_ACCESSDENIED | The caller does not have enough permissions for renaming the element.| |STG_E_FILENOTFOUND | The element with the specified old name does not exist.| |STG_E_FILEALREADYEXISTS | The element specified by the new name already exists.| |STG_E_INSUFFICIENTMEMORY | The element was not renamed due to a lack of memory.| |STG_E_INVALIDNAME | Invalid value for one of the names.| |STG_E_INVALIDPOINTER | The pointer specified for the element was not valid.| |STG_E_INVALIDPARAMETER | One of the parameters was not valid.| |STG_E_REVERTED | The storage object has been invalidated by a revert operation above it in the transaction tree.| |STG_E_TOOMANYOPENFILES | The element was not renamed because there are too many open files.| IStorage::RenameElement renames the specified substorage or stream in this storage object. An element in a storage object cannot be renamed while it is open. The rename operation is subject to committing the changes if the storage is open in transacted mode. The IStorage::RenameElement method is not guaranteed to work in low memory with storage objects open in transacted mode. It may work in direct mode. Read more on docs.microsoft.com. The SetElementTimes method sets the modification, access, and creation times of the specified storage element, if the underlying file system supports this method. The name of the storage object element whose times are to be modified. If NULL, the time is set on the root storage rather than one of its elements. Either the new creation time for the element or NULL if the creation time is not to be modified. Either the new access time for the element or NULL if the access time is not to be modified. Either the new modification time for the element or NULL if the modification time is not to be modified. This method can return one of these values. | Return code | Description | |----------------|---------------| |S_OK | The time values were successfully set.| |E_PENDING | Asynchronous Storage only: Part or all of the element's data is currently unavailable.| |STG_E_ACCESSDENIED | The caller does not have enough permissions for changing the element.| |STG_E_FILENOTFOUND | The element with the specified name does not exist.| |STG_E_INSUFFICIENTMEMORY | The element was not changed due to a lack of memory.| |STG_E_INVALIDNAME | Not a valid value for the element name.| |STG_E_INVALIDPOINTER | The pointer specified for the element was not valid.| |STG_E_INVALIDPARAMETER | One of the parameters was not valid.| |STG_E_TOOMANYOPENFILES | The element was not changed because there are too many open files.| |STG_E_REVERTED | The storage object has been invalidated by a revert operation above it in the transaction tree.| SetElementTimes sets time statistics for the specified storage element within this storage object. Not all file systems support all the time values. This method sets those times that are supported and ignores the rest. Each time-value parameter can be NULL; indicating that no modification should occur. Call the IStorage::Stat method to retrieve these time values. Read more on docs.microsoft.com. The SetClass method assigns the specified class identifier (CLSID) to this storage object. The CLSID that is to be associated with the storage object. This method can return one of these values. | Return code | Description | |----------------|---------------| |S_OK | The CLSID was successfully assigned.| |E_PENDING | Asynchronous Storage only: Part or all of the storage's data is currently unavailable.| |STG_E_ACCESSDENIED | The caller does not have enough permissions for assigning a CLSID to the storage object.| |STG_E_MEDIUMFULL | Not enough space was left on device to complete the operation.| |STG_E_REVERTED | The storage object has been invalidated by a revert operation above it in the transaction tree.| When first created, a storage object has an associated CLSID of CLSID_NULL. Call SetClass to assign a CLSID to the storage object. Call the IStorage::Stat method to retrieve the current CLSID of a storage object. Read more on docs.microsoft.com. The SetStateBits method stores up to 32 bits of state information in this storage object. Specifies the new values of the bits to set. No legal values are defined for these bits; they are all reserved for future use and must not be used by applications. A binary mask indicating which bits in grfStateBits are significant in this call. This method can return one of these values. | Return code | Description | |----------------|---------------| |S_OK | The state information was successfully set.| |E_PENDING | Asynchronous Storage only: Part or all of the storage's data is currently unavailable. | |STG_E_ACCESSDENIED | The caller does not have enough permissions for changing this storage object.| |STG_E_INVALIDFLAG | The value for the grfStateBits or *grfMask* parameter is not valid.| |STG_E_INVALIDPARAMETER | One of the parameters was not valid.| The values for the state bits are not currently defined. The Stat method retrieves the STATSTG structure for this open storage object. On return, pointer to a STATSTG structure where this method places information about the open storage object. This parameter is NULL if an error occurs. Read more on docs.microsoft.com. Specifies that some of the members in the STATSTG structure are not returned, thus saving a memory allocation operation. Values are taken from the STATFLAG enumeration. Read more on docs.microsoft.com. This method can return one of these values. | Return code | Description | |----------------|---------------| |S_OK | The STATSTG structure was successfully returned at the specified location.| |E_PENDING | Asynchronous Storage only: Part or all of the storage's data is currently unavailable.| |STG_E_ACCESSDENIED | The caller does not have enough permissions for accessing statistics for this storage object.| |STG_E_INSUFFICIENTMEMORY | The STATSTG structure was not returned due to a lack of memory.| |STG_E_INVALIDFLAG | The value for the *grfStateFlag* parameter is not valid.| |STG_E_INVALIDPARAMETER | One of the parameters was not valid.| IStorage::Stat retrieves the STATSTG structure for the current storage object. The STATSTG structure contains statistical information about the storage object. IStorage::EnumElements returns a pointer to an enumerator object. The enumerator object returned by this method implements the IEnumSTATSTG interface, through which the data stored in the array of the STATSTG structures is enumerated. Read more on docs.microsoft.com. The IID guid for this interface. {0000000b-0000-0000-c000-000000000046} The PROPVARIANT structure is used in the ReadMultiple and WriteMultiple methods of IPropertyStorage to define the type tag and the value of a property in a property set. The PROPVARIANT structure can also hold a value of VT_DECIMAL: This doc was truncated. Read more on docs.microsoft.com. Describes a pointer. Learn more about this API from docs.microsoft.com. Pointer to a function. Pointer to a variable, constant, or data member. The ITypeComp that binds the pointer. Contains parameters used during a moniker-binding operation. A BIND_OPTS structure is stored in a bind context; the same bind context is used by each component of a composite moniker during binding, allowing the same parameters to be passed to all components of a composite moniker. See IBindCtx for more information about bind contexts. Moniker clients (use a moniker to acquire an interface pointer to an object) typically do not need to specify values for the members of this structure. The CreateBindCtx function creates a bind context with the bind options set to default values that are suitable for most situations; the BindMoniker function does the same thing when creating a bind context for use in binding a moniker. If you want to modify the values of these bind options, you can do so by passing a BIND_OPTS structure to the IBindCtx::SetBindOptions method. Moniker implementers can pass a BIND_OPTS structure to the IBindCtx::GetBindOptions method to retrieve the values of these bind options. Read more on docs.microsoft.com. The size of this structure, in bytes. Flags that control aspects of moniker binding operations. This value is any combination of the bit flags in the BIND_FLAGS enumeration. The CreateBindCtx function initializes this member to zero. Flags that should be used when opening the file that contains the object identified by the moniker. Possible values are the STGM constants. The binding operation uses these flags in the call to IPersistFile::Load when loading the file. If the object is already running, these flags are ignored by the binding operation. The CreateBindCtx function initializes this field to STGM_READWRITE. The clock time by which the caller would like the binding operation to be completed, in milliseconds. This member lets the caller limit the execution time of an operation when speed is of primary importance. A value of zero indicates that there is no deadline. Callers most often use this capability when calling the IMoniker::GetTimeOfLastChange method, though it can be usefully applied to other operations as well. The CreateBindCtx function initializes this field to zero. Typical deadlines allow for a few hundred milliseconds of execution. This deadline is a recommendation, not a requirement; however, operations that exceed their deadline by a large amount may cause delays for the end user. Each moniker implementation should try to complete its operation by the deadline, or fail with the error MK_E_EXCEEDEDDEADLINE. If a binding operation exceeds its deadline because one or more objects that it needs are not running, the moniker implementation should register the objects responsible in the bind context using the IBindCtx::RegisterObjectParam. The objects should be registered under the parameter names "ExceededDeadline", "ExceededDeadline1", "ExceededDeadline2", and so on. If the caller later finds the object in the running object table, the caller can retry the binding operation. The GetTickCount function indicates the number of milliseconds since system startup, and wraps back to zero after 2^31 milliseconds. Consequently, callers should be careful not to inadvertently pass a zero value (which indicates no deadline), and moniker implementations should be aware of clock wrapping problems. Read more on docs.microsoft.com. The BLOB structure (nspapi.h), which is derived from Binary Large Object, contains information about a block of data. The structure name BLOB comes from the acronym BLOB, which stands for Binary Large Object. This structure does not describe the nature of the data pointed to by pBlobData.
Note  Windows Sockets defines a similar BLOB structure in Wtypes.h. Using both header files in the same source code file creates redefinition–compile time errors.
 
 Read more on docs.microsoft.com. Size of the block of data pointed to by pBlobData, in bytes. Pointer to a block of data. Identifies the calling convention used by a member function described in the METHODDATA structure. Learn more about this API from docs.microsoft.com. Values that are used in activation calls to indicate the execution contexts in which an object is to be run. Values from the CLSCTX enumeration are used in activation calls (CoCreateInstance, CoCreateInstanceEx, CoGetClassObject, and so on) to indicate the preferred execution contexts (in-process, local, or remote) in which an object is to be run. They are also used in calls to CoRegisterClassObject to indicate the set of execution contexts in which a class object is to be made available for requests to construct instances (IClassFactory::CreateInstance). To indicate that more than one context is acceptable, you can combine multiple values with Boolean ORs. The contexts are tried in the order in which they are listed. Given a set of CLSCTX flags, the execution context to be used depends on the availability of registered class codes and other parameters according to the following algorithm. This doc was truncated. Read more on docs.microsoft.com. The code that creates and manages objects of this class is a DLL that runs in the same process as the caller of the function specifying the class context. The code that manages objects of this class is an in-process handler. This is a DLL that runs in the client process and implements client-side structures of this class when instances of the class are accessed remotely. The EXE code that creates and manages objects of this class runs on same machine but is loaded in a separate process space. Obsolete. A remote context. The LocalServer32 or LocalService code that creates and manages objects of this class is run on a different computer. Obsolete. Reserved. Reserved. Reserved. Reserved. Disables the downloading of code from the directory service or the Internet. This flag cannot be set at the same time as CLSCTX_ENABLE_CODE_DOWNLOAD. Reserved. Specify if you want the activation to fail if it uses custom marshalling. Enables the downloading of code from the directory service or the Internet. This flag cannot be set at the same time as CLSCTX_NO_CODE_DOWNLOAD. The CLSCTX_NO_FAILURE_LOG can be used to override the logging of failures in CoCreateInstanceEx. If the ActivationFailureLoggingLevel is created, the following values can determine the status of event logging: This doc was truncated. Read more on docs.microsoft.com. Disables activate-as-activator (AAA) activations for this activation only. This flag overrides the setting of the EOAC_DISABLE_AAA flag from the EOLE_AUTHENTICATION_CAPABILITIES enumeration. This flag cannot be set at the same time as CLSCTX_ENABLE_AAA. Any activation where a server process would be launched under the caller's identity is known as an activate-as-activator (AAA) activation. Disabling AAA activations allows an application that runs under a privileged account (such as LocalSystem) to help prevent its identity from being used to launch untrusted components. Library applications that use activation calls should always set this flag during those calls. This helps prevent the library application from being used in an escalation-of-privilege security attack. This is the only way to disable AAA activations in a library application because the EOAC_DISABLE_AAA flag from the EOLE_AUTHENTICATION_CAPABILITIES enumeration is applied only to the server process and not to the library application. Windows 2000:  This flag is not supported. Read more on docs.microsoft.com. Enables activate-as-activator (AAA) activations for this activation only. This flag overrides the setting of the EOAC_DISABLE_AAA flag from the EOLE_AUTHENTICATION_CAPABILITIES enumeration. This flag cannot be set at the same time as CLSCTX_DISABLE_AAA. Any activation where a server process would be launched under the caller's identity is known as an activate-as-activator (AAA) activation. Enabling this flag allows an application to transfer its identity to an activated component. Windows 2000:  This flag is not supported. Read more on docs.microsoft.com. Begin this activation from the default context of the current apartment. Activate or connect to a 32-bit version of the server; fail if one is not registered. Activate or connect to a 64 bit version of the server; fail if one is not registered. When this flag is specified, COM uses the impersonation token of the thread, if one is present, for the activation request made by the thread. When this flag is not specified or if the thread does not have an impersonation token, COM uses the process token of the thread's process for the activation request made by the thread. Windows Vista or later:  This flag is supported. Read more on docs.microsoft.com. Indicates activation is for an app container.
Note  This flag is reserved for internal use and is not intended to be used directly from your code.
 
 Read more on docs.microsoft.com. Specify this flag for Interactive User activation behavior for As-Activator servers. A strongly named Medium IL Windows Store app can use this flag to launch an "As Activator" COM server without a strong name. Also, you can use this flag to bind to a running instance of the COM server that's launched by a desktop application. The client must be Medium IL, it must be strongly named, which means that it has a SysAppID in the client token, it can't be in session 0, and it must have the same user as the session ID's user in the client token. If the server is out-of-process and "As Activator", it launches the server with the token of the client token's session user. This token won't be strongly named. If the server is out-of-process and RunAs "Interactive User", this flag has no effect. If the server is out-of-process and is any other RunAs type, the activation fails. This flag has no effect for in-process servers. Off-machine activations fail when they use this flag. Read more on docs.microsoft.com. Used for loading Proxy/Stub DLLs.
Note  This flag is reserved for internal use and is not intended to be used directly from your code.
 
 Read more on docs.microsoft.com. Identifies the type description being bound to. Learn more about this API from docs.microsoft.com. No match was found. A FUNCDESC was returned. A VARDESC was returned. A TYPECOMP was returned. An IMPLICITAPPOBJ was returned. The end of the enum. Contains the arguments passed to a method or property. Learn more about this API from docs.microsoft.com. An array of arguments. **Note**: these arguments appear in reverse order Read more on docs.microsoft.com. The dispatch IDs of the named arguments. The number of arguments. The number of named arguments. Specifies the desired data or view aspect of the object when drawing or getting data. Values of this enumeration are used to define the dwAspect member of the FORMATETC structure. Only one DVASPECT value can be used to specify a single presentation aspect in a FORMATETC structure. The FORMATETC structure is used in many OLE functions and interface methods that require information on data presentation. The default value of MiscStatus 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
 Read more on docs.microsoft.com. Provides a representation of an object so it can be displayed as an embedded object inside of a container. This value is typically specified for compound document objects. The presentation can be provided for the screen or printer. Provides a thumbnail representation of an object so it can be displayed in a browsing tool. The thumbnail is approximately a 120 by 120 pixel, 16-color (recommended) device-independent bitmap potentially wrapped in a metafile. Provides an iconic representation of an object. Provides a representation of the object on the screen as though it were printed to a printer using the Print command from the File menu. The described data may represent a sequence of pages. Specifies information about the target device for which data is being composed. DVTARGETDEVICE contains enough information about a Windows target device so a handle to a device context (HDC) can be created using the CreateDC function. Some OLE 1 client applications incorrectly construct target devices by allocating too few bytes in the DEVMODE structure for the DVTARGETDEVICE. They typically only supply the number of bytes in the dmSize member of DEVMODE. The number of bytes to be allocated should be the sum of dmSize + dmDriverExtra. When a call is made to the CreateDC function with an incorrect target device, the printer driver tries to access the additional bytes and unpredictable results can occur. To help protect against a crash and make the additional bytes available, OLE pads the size of OLE 2 target devices created from OLE 1 target devices. The size, in bytes, of the DVTARGETDEVICE structure. The initial size is included so the structure can be copied more easily. The offset, in bytes, from the beginning of the structure to the device driver name, which is stored as a NULL-terminated string in the tdData buffer. The offset, in bytes, from the beginning of the structure to the device name, which is stored as a NULL-terminated string in the tdData buffer. This value can be zero to indicate no device name. The offset, in bytes, from the beginning of the structure to the port name, which is stored as a NULL-terminated string in the tdData buffer. This value can be zero to indicate no port name. The offset, in bytes, from the beginning of the structure to the DEVMODE structure retrieved by calling DocumentProperties. An array of bytes containing data for the target device. It is not necessary to include empty strings in tdData (for names where the offset value is zero). Computes the amount of memory that must be allocated to store this struct, including the specified number of elements in the variable length inline array at the end. The ELEMDESC structure contains the type description and process-transfer information for a variable, a function, or a function parameter. (ELEMDESC) The type of the element. Describes an exception that occurred during IDispatch::Invoke. Use the pfnDeferredFillIn field to enable an object to defer filling in the bstrDescription, bstrHelpFile, and dwHelpContext fields until they are needed. This field might be used, for example, if loading the string for the error is a time-consuming operation. To use deferred fill-in, the object puts a function pointer in this slot and does not fill any of the other fields except wCode, which is required. To get additional information, the caller passes the EXCEPINFO structure back to the pexcepinfo callback function, which fills in the additional information. When the ActiveX object and the ActiveX client are in different processes, the ActiveX object calls pfnDeferredFillIn before returning to the controller. Read more on docs.microsoft.com. The error code. Error codes should be greater than 1000. Either this field or the scode field must be filled in; the other must be set to 0. Reserved. Should be 0. The name of the exception source. Typically, this is an application name. This field should be filled in by the implementer of IDispatch. The exception description to display. If no description is available, use null. The fully qualified help file path. If no Help is available, use null. The help context ID. Reserved. Must be null. Provides deferred fill-in. If deferred fill-in is not desired, this field should be set to null. A return value that describes the error. Either this field or wCode (but not both) must be filled in; the other must be set to 0. (16-bit Windows versions only.) Represents a generalized clipboard format. The FORMATETC structure is used by methods in the data transfer and presentation interfaces as a parameter specifying the data being transferred. For example, the IDataObject::GetData method uses the FORMATETC structure to indicate exactly what kind of data the caller is requesting. The clipboard format of interest. There are three types of formats recognized by OLE: This doc was truncated. Read more on docs.microsoft.com. A pointer to a DVTARGETDEVICE structure containing information about the target device for which the data is being composed. A NULL value is used whenever the specified data format is independent of the target device or when the caller doesn't care what device is used. In the latter case, if the data requires a target device, the object should pick an appropriate default device (often the display for visual components). Data obtained from an object with a NULL target device, such as most metafiles, is independent of the target device. The resulting data is usually the same as it would be if the user chose the Save As command from the File menu and selected an interchange format. Indicates how much detail should be contained in the rendering. This parameter should be one of the DVASPECT enumeration values. A single clipboard format can support multiple aspects or views of the object. Most data and presentation transfer and caching methods pass aspect information. For example, a caller might request an object's iconic picture, using the metafile clipboard format to retrieve it. Note that only one DVASPECT value can be used in dwAspect. That is, dwAspect cannot be the result of a Boolean OR operation on several DVASPECT values. Part of the aspect when the data must be split across page boundaries. The most common value is -1, which identifies all of the data. For the aspects DVASPECT_THUMBNAIL and DVASPECT_ICON, lindex is ignored. One of the TYMED enumeration constants which indicate the type of storage medium used to transfer the object's data. Data can be transferred using whatever medium makes sense for the object. For example, data can be passed using global memory, a disk file, or structured storage objects. For more information, see the TYMED enumeration. Describes a function. (FUNCDESC) The cParams field specifies the total number of required and optional parameters. The cParamsOpt field specifies the form of optional parameters accepted by the function, as follows: This doc was truncated. Read more on docs.microsoft.com. The function member ID. The status code. Description of the element. Indicates the type of function (virtual, static, or dispatch-only). The invocation type. Indicates whether this is a property function, and if so, which type. The calling convention. The total number of parameters. The number of optional parameters. For FUNC_VIRTUAL, specifies the offset in the VTBL. The number of possible return values. The function return type. The function flags. See FUNCFLAGS. Specifies function flags. FUNCFLAG_FHIDDEN means that the property should never be shown in object browsers, property browsers, and so on. This function is useful for removing items from an object model. Code can bind to the member, but the user will never know that the member exists. FUNCFLAG_FNONBROWSABLE means that the property should not be displayed in a properties browser. It is used in circumstances in which an error would occur if the property were shown in a properties browser. FUNCFLAG_FRESRICTED means that macro-oriented programmers should not be allowed to access this member. These members are usually treated as _FHIDDEN by tools such as Visual Basic, with the main difference being that code cannot bind to those members. Read more on docs.microsoft.com. The function should not be accessible from macro languages. This flag is intended for system-level functions or functions that type browsers should not display. The function returns an object that is a source of events. The function that supports data binding. When set, any call to a method that sets the property results first in a call to IPropertyNotifySink::OnRequestEdit. The implementation of OnRequestEdit determines if the call is allowed to set the property. The function that is displayed to the user as bindable. FUNC_FBINDABLE must also be set. The function that best represents the object. Only one function in a type information can have this attribute. The function should not be displayed to the user, although it exists and is bindable. The function supports GetLastError. If an error occurs during the function, the caller can call GetLastError to retrieve the error code. Permits an optimization in which the compiler looks for a member named xyz on the type of abc. If such a member is found and is flagged as an accessor function for an element of the default collection, then a call is generated to that member function. Permitted on members in dispinterfaces and interfaces; not permitted on modules. For more information, refer to defaultcollelem in Type Libraries and the Object Description Language. The type information member is the default member for display in the user interface. The property appears in an object browser, but not in a properties browser. Tags the interface as having default behaviors. Mapped as individual bindable properties. Specifies the function type. Learn more about this API from docs.microsoft.com. The function is accessed the same as PUREVIRTUAL, except the function has an implementation. The function is accessed through the virtual function table (VTBL), and takes an implicit this pointer. The function is accessed by static address and takes an implicit this pointer. The function is accessed by static address and does not take an implicit this pointer. The function can be accessed only through IDispatch. Called by the server to notify a data object's currently registered advise sinks that data in the object has changed. A pointer to a FORMATETC structure, which describes the format, target device, rendering, and storage information of the calling data object. A pointer to a STGMEDIUM structure, which defines the storage medium (global memory, disk file, storage object, stream object, GDI object, or undefined) and ownership of that medium for the calling data object. Object handlers and containers of link objects implement IAdviseSink::OnDataChange to take appropriate steps when notified that data in the object has changed. They also must call IDataObject::DAdvise to set up advisory connections with the objects in whose data they are interested. Containers that take advantage of OLE's caching support do not need to register for data-change notifications, because the information necessary to update the container's presentation of the object, including any changes in its data, are maintained in the object's cache.

Notes to Implementers

If you implement IAdviseSink::OnDataChange for a container, remember that this method is asynchronous and that making synchronous calls within asynchronous methods is not valid. Therefore, you cannot call IDataObject::GetData to obtain the data you need to update your object. Instead, you either post an internal message, or invalidate the rectangle for the changed data by calling InvalidateRect and waiting for a WM_PAINT message, at which point you are free to get the data and update the object. The data itself, which is valid only for the duration of the call, is passed using the storage medium pointed to by pStgmed. Since the caller owns the medium, the advise sink should not free it. Also, if pStgmed points to an IStorage or IStream interface, the sink must not increment the reference count. Read more on docs.microsoft.com. Notifies an object's registered advise sinks that its view has changed. The aspect, or view, of the object. Contains a value taken from the DVASPECT enumeration. The portion of the view that has changed. Currently only -1 is valid. Containers register to be notified when an object's view changes by calling IViewObject::SetAdvise. After it is registered, the object will call the sink's IAdviseSink::OnViewChange method when appropriate. OnViewChange can be called when the object is in either the loaded or running state. Even though DVASPECT values are individual flag bits, dwAspect may represent only one value. That is, dwAspect cannot contain the result of an OR operation combining two or more DVASPECT values. The lindex parameter represents the part of the aspect that is of interest. The value of lindex depends on the value of dwAspect. If dwAspect is either DVASPECT_THUMBNAIL or DVASPECT_ICON, lindex is ignored. If dwAspect is DVASPECT_CONTENT, lindex must be -1, which indicates that the entire view is of interest and is the only value that is currently valid. Read more on docs.microsoft.com. Called by the server to notify all registered advisory sinks that the object has been renamed. A pointer to the IMoniker interface on the new full moniker of the object. OLE link objects normally implement IAdviseSink::OnRename to receive notification of a change in the name of a link source or its container. The object serving as the link source calls OnRename and passes its new full moniker to the object handler, which forwards the notification to the link object. In response, the link object must update its moniker. The link object, in turn, forwards the notification to its own container. Called by the server to notify all registered advisory sinks that the object has been saved. Object handlers and link objects normally implement IAdviseSink::OnSave to receive notifications of when an object is saved to disk, either to its original storage (through a Save operation) or to new storage (through a Save As operation). Object Handlers and link objects register to be notified when an object is saved for the purpose of updating their caches, but then only if the advise flag passed during registration specifies ADVFCACHE_ONSAVE. Object handlers and link objects forward these notifications to their containers. Called by the server to notify all registered advisory sinks that the object has changed from the running to the loaded state. The OnClose notification indicates that an object is making the transition from the running to the loaded state, so its container can take appropriate measures to ensure an orderly shutdown. For example, an object handler must release its pointer to the object. If the object that is closing is the last open object supported by its OLE server application, the application can also shut down. In the case of a link object, the notification that the object is closing should always be interpreted to mean that the connection to the link source has broken. Read more on docs.microsoft.com. The IID guid for this interface. {0000010f-0000-0000-c000-000000000046} Registers an object with the bind context to ensure that the object remains active until the bind context is released. A pointer to the IUnknown interface on the object that is being registered as bound. This method can return the standard return values E_OUTOFMEMORY and S_OK. Those writing a new moniker class (through an implementation of the IMoniker interface) should call this method whenever the implementation activates an object. This happens most often in the course of binding a moniker, but it can also happen while retrieving a moniker's display name, parsing a display name into a moniker, or retrieving the time that an object was last modified. RegisterObjectBound calls AddRef to create an additional reference to the object. You must, however, still release your own copy of the pointer. Calling this method twice for the same object creates two references to that object. You can release a reference obtained through a call to this method by calling IBindCtx::RevokeObjectBound. All references held by the bind context are released when the bind context itself is released. Calling RegisterObjectBound to register an object with a bind context keeps the object active until the bind context is released. Reusing a bind context in a subsequent binding operation (either for another piece of the same composite moniker or for a different moniker) can make the subsequent binding operation more efficient because it doesn't have to reload that object. This, however, improves performance only if the subsequent binding operation requires some of the same objects as the original one, so you need to balance the possible performance improvement of reusing a bind context against the costs of keeping objects activated unnecessarily. IBindCtx does not provide a method to retrieve a pointer to an object registered using RegisterObjectBound. Assuming the object has registered itself with the running object table, moniker implementations can call IRunningObjectTable::GetObject to retrieve a pointer to the object. Read more on docs.microsoft.com. Removes the object from the bind context, undoing a previous call to RegisterObjectBound. A pointer to the IUnknown interface on the object to be removed. This method can return the following values. This doc was truncated. You would rarely call this method. It is documented primarily for completeness. Releases all pointers to all objects that were previously registered by calls to RegisterObjectBound. If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. You rarely call this method directly. The system's IBindCtx implementation calls this method when the pointer to the IBindCtx interface on the bind context is released (the bind context is released). If a bind context is not released, all of the registered objects remain active. If the same object has been registered more than once, this method calls the Release method on the object the number of times it was registered. Read more on docs.microsoft.com. Sets new values for the binding parameters stored in the bind context. A pointer to a [BIND_OPTS3](/windows/win32/api/objidl/ns-objidl-bind_opts3-r1) structure containing the binding parameters. This method can return the standard return values E_OUTOFMEMORY and S_OK. A bind context contains a block of parameters that are common to most IMoniker operations. These parameters do not change as the operation moves from piece to piece of a composite moniker. Subsequent binding operations can call IBindCtx::GetBindOptions to retrieve these parameters.

Notes to Callers

This method can be called by moniker clients (those who use monikers to acquire interface pointers to objects). When you first create a bind context by using the CreateBindCtx function, the fields of the BIND_OPTS structure are initialized to the following values: This doc was truncated. Read more on docs.microsoft.com. Retrieves the binding options stored in this bind context. A pointer to an initialized structure that receives the current binding parameters on return. See [BIND_OPTS3](/windows/win32/api/objidl/ns-objidl-bind_opts3-r1). This method can return the standard return values E_UNEXPECTED and S_OK. A bind context contains a block of parameters that are common to most IMoniker operations and that do not change as the operation moves from piece to piece of a composite moniker.

Notes to Callers

You typically call this method if you are writing your own moniker class. (This requires that you implement the IMoniker interface.) You call this method to retrieve the parameters specified by the moniker client. You must initialize the structure that is filled in by this method. Before calling this method, you must initialize the cbStruct member to the size of the structure. Read more on docs.microsoft.com. Retrieves an interface pointer to the running object table (ROT) for the computer on which this bind context is running. The address of a IRunningObjectTable* pointer variable that receives the interface pointer to the running object table. If an error occurs, *pprot is set to NULL. If *pprot is non-NULL, the implementation calls AddRef on the running table object; it is the caller's responsibility to call Release. This method can return the standard return values E_OUTOFMEMORY, E_UNEXPECTED, and S_OK. The running object table is a globally accessible table on each computer. It keeps track of all the objects that are currently running on the computer.

Notes to Callers

Typically, those implementing a new moniker class (through an implementation of IMoniker interface) call GetRunningObjectTable. It is useful to call this method in an implementation of IMoniker::BindToObject or IMoniker::IsRunning to check whether an object is currently running. You can also call this method in the implementation of IMoniker::GetTimeOfLastChange to learn when a running object was last modified. Moniker implementations should call this method instead of using the GetRunningObjectTable function. This makes it possible for future implementations of IBindCtx to modify binding behavior. Read more on docs.microsoft.com. Associates an object with a string key in the bind context's string-keyed table of pointers. The bind context string key under which the object is being registered. Key string comparison is case-sensitive. A pointer to the IUnknown interface on the object that is to be registered. The method calls AddRef on the pointer. Read more on docs.microsoft.com. This method can return the standard return values E_OUTOFMEMORY and S_OK. A bind context maintains a table of interface pointers, each associated with a string key. This enables communication between a moniker implementation and the caller that initiated the binding operation. One party can store an interface pointer under a string known to both parties so that the other party can later retrieve it from the bind context. Binding operations subsequent to the use of this method can use IBindCtx::GetObjectParam to retrieve the stored pointer.

Notes to Callers

RegisterObjectParam is useful to those implementing a new moniker class (through an implementation of IMoniker) and to moniker clients (those who use monikers to bind to objects). In implementing a new moniker class, you call this method when an error occurs during moniker binding to inform the caller of the cause of the error. The key that you would obtain with a call to this method would depend on the error condition. Following is a list of common moniker binding errors, describing for each the keys that would be appropriate: This doc was truncated. Read more on docs.microsoft.com. Retrieves an interface pointer to the object associated with the specified key in the bind context's string-keyed table of pointers. The bind context string key to be searched for. Key string comparison is case-sensitive. The address of an IUnknown* pointer variable that receives the interface pointer to the object associated with pszKey. When successful, the implementation calls AddRef on *ppunk. It is the caller's responsibility to call Release. If an error occurs, the implementation sets *ppunk to NULL. If the method succeeds, the return value is S_OK. Otherwise, it is E_FAIL. A bind context maintains a table of interface pointers, each associated with a string key. This enables communication between a moniker implementation and the caller that initiated the binding operation. One party can store an interface pointer under a string known to both parties so that the other party can later retrieve it from the bind context. The pointer this method retrieves must have previously been inserted into the table using the IBindCtx::RegisterObjectParam method.

Notes to Callers

Objects using monikers to locate other objects can call this method when a binding operation fails to get specific information about the error that occurred. Depending on the error, it may be possible to correct the situation and retry the binding operation. See IBindCtx::RegisterObjectParam for more information. Moniker implementations can call this method to handle situations where a caller initiates a binding operation and requests specific information. By convention, the implementer should use key names that begin with the string form of the CLSID of a moniker class. (See the StringFromCLSID function.) Read more on docs.microsoft.com. Retrieves a pointer to an interface that can be used to enumerate the keys of the bind context's string-keyed table of pointers. The address of an IEnumString* pointer variable that receives the interface pointer to the enumerator. If an error occurs, *ppenum is set to NULL. If *ppenum is non-NULL, the implementation calls AddRef on *ppenum; it is the caller's responsibility to call Release. This method can return the standard return values E_OUTOFMEMORY and S_OK. The keys returned by the enumerator are the ones previously specified in calls to IBindCtx::RegisterObjectParam.

Notes to Callers

A bind context maintains a table of interface pointers, each associated with a string key. This enables communication between a moniker implementation and the caller that initiated the binding operation. One party can store an interface pointer under a string known to both parties so that the other party can later retrieve it from the bind context. In the system implementation of the IBindCtx interface, this method is not implemented. Therefore, calling this method results in a return value of E_NOTIMPL. Read more on docs.microsoft.com. Removes the specified key and its associated pointer from the bind context's string-keyed table of objects. The key must have previously been inserted into the table with a call to RegisterObjectParam. The bind context string key to be removed. Key string comparison is case-sensitive. This method can return the following values. This doc was truncated. A bind context maintains a table of interface pointers, each associated with a string key. This enables communication between a moniker implementation and the caller that initiated the binding operation. One party can store an interface pointer under a string known to both parties so that the other party can later retrieve it from the bind context. This method is used to remove an entry from the table. If the specified key is found, the bind context also releases its reference to the object. Read more on docs.microsoft.com. The IID guid for this interface. {0000000e-0000-0000-c000-000000000046} Called by a data consumer to obtain data from a source data object. A pointer to the FORMATETC structure that defines the format, medium, and target device to use when passing the data. It is possible to specify more than one medium by using the Boolean OR operator, allowing the method to choose the best medium among those specified. A pointer to the STGMEDIUM structure that indicates the storage medium containing the returned data through its tymed member, and the responsibility for releasing the medium through the value of its pUnkForRelease member. If pUnkForRelease is NULL, the receiver of the medium is responsible for releasing it; otherwise, pUnkForRelease points to the IUnknown on the appropriate object so its Release method can be called. The medium must be allocated and filled in by GetData. This method returns S_OK on success. Other possible values include the following. This doc was truncated. A data consumer calls GetData to retrieve data from a data object, conveyed through a storage medium (defined through the STGMEDIUM structure).

Notes to Callers

You can specify more than one acceptable tymed medium with the Boolean OR operator. GetData must choose from the OR'd values the medium that best represents the data, do the allocation, and indicate responsibility for releasing the medium. Data transferred across a stream extends from position zero of the stream pointer through to the position immediately before the current stream pointer (that is, the stream pointer position upon exit).

Notes to Implementers

GetData must check all fields in the FORMATETC structure. It is important that GetData render the requested aspect and, if possible, use the requested medium. If the data object cannot comply with the information specified in the FORMATETC, the method should return DV_E_FORMATETC. If an attempt to allocate the medium fails, the method should return STG_E_MEDIUMFULL. It is important to fill in all of the fields in the STGMEDIUM structure. Although the caller can specify more than one medium for returning the data, GetData can provide only one medium. If the initial transfer fails with the selected medium, this method can be implemented to try one of the other media specified before returning an error. Read more on docs.microsoft.com. Called by a data consumer to obtain data from a source data object. This method differs from the GetData method in that the caller must allocate and free the specified storage medium. A pointer to the FORMATETC structure that defines the format, medium, and target device to use when passing the data. Only one medium can be specified in tymed, and only the following values are valid: TYMED_ISTORAGE, TYMED_ISTREAM, TYMED_HGLOBAL, or TYMED_FILE. A pointer to the STGMEDIUM structure that defines the storage medium containing the data being transferred. The medium must be allocated by the caller and filled in by GetDataHere. The caller must also free the medium. The implementation of this method must always supply a value of NULL for the punkForRelease member of the STGMEDIUM structure to which this parameter points. This method returns S_OK on success. Other possible values include the following. This doc was truncated. The GetDataHere method is similar to IDataObject::GetData, except that the caller must both allocate and free the medium specified in pmedium. GetDataHere renders the data described in a FORMATETC structure and copies the data into that caller-provided STGMEDIUM structure. For example, if the medium is TYMED_HGLOBAL, this method cannot resize the medium or allocate a new hGlobal. Some media are not appropriate in a call to GetDataHere, including GDI types such as metafiles. The GetDataHere method cannot put data into a caller-provided metafile. In general, the only storage media it is necessary to support in this method are TYMED_ISTORAGE, TYMED_ISTREAM, and TYMED_FILE. When the transfer medium is a stream, OLE makes assumptions about where the data is being returned and the position of the stream's seek pointer. In a GetData call, the data returned is from stream position zero through just before the current seek pointer of the stream (that is, the position on exit). For GetDataHere, the data returned is from the stream position on entry through just before the position on exit. Read more on docs.microsoft.com. Determines whether the data object is capable of rendering the data as specified. Objects attempting a paste or drop operation can call this method before calling IDataObject::GetData to get an indication of whether the operation may be successful. A pointer to the FORMATETC structure defining the format, medium, and target device to use for the query. This method returns S_OK on success. Other possible values include the following This doc was truncated. The client of a data object calls QueryGetData to determine whether passing the specified FORMATETC structure to a subsequent call to IDataObject::GetData is likely to be successful. A successful return from this method does not necessarily ensure the success of the subsequent paste or drop operation. Provides a potentially different but logically equivalent FORMATETC structure. You use this method to determine whether two different FORMATETC structures would return the same data, removing the need for duplicate rendering. A pointer to the FORMATETC structure that defines the format, medium, and target device that the caller would like to use to retrieve data in a subsequent call such as IDataObject::GetData. The tymed member is not significant in this case and should be ignored. A pointer to a FORMATETC structure that contains the most general information possible for a specific rendering, making it canonically equivalent to pformatetcIn. The caller must allocate this structure and the GetCanonicalFormatEtc method must fill in the data. To retrieve data in a subsequent call like IDataObject::GetData, the caller uses the specified value of pformatetcOut, unless the value specified is NULL. This value is NULL if the method returns DATA_S_SAMEFORMATETC. The tymed member is not significant in this case and should be ignored. This method can return the following values. This doc was truncated. If a data object can supply exactly the same data for more than one requested FORMATETC structure, GetCanonicalFormatEtc can supply a "canonical", or standard FORMATETC that gives the same rendering as a set of more complicated FORMATETC structures. For example, it is common for the data returned to be insensitive to the target device specified in any one of a set of otherwise similar FORMATETC structures.

Notes to Callers

A call to this method can determine whether two calls to IDataObject::GetData on a data object, specifying two different FORMATETC structures, would actually produce the same renderings, thus eliminating the need for the second call and improving performance. If the call to GetCanonicalFormatEtc results in a canonical format being written to the pformatetcOut parameter, the caller then uses that structure in a subsequent call to IDataObject::GetData.

Notes to Implementers

Conceptually, it is possible to think of FORMATETC structures in groups defined by a canonical FORMATETC that provides the same results as each of the group members. In constructing the canonical FORMATETC, you should make sure it contains the most general information possible that still produces a specific rendering. For data objects that never provide device-specific renderings, the simplest implementation of this method is to copy the input FORMATETC to the output FORMATETC, store a NULL in the ptd member of the output FORMATETC, and return DATA_S_SAMEFORMATETC. Read more on docs.microsoft.com. Called by an object containing a data source to transfer data to the object that implements this method. A pointer to the FORMATETC structure defining the format used by the data object when interpreting the data contained in the storage medium. A pointer to the STGMEDIUM structure defining the storage medium in which the data is being passed. If TRUE, the data object called, which implements SetData, owns the storage medium after the call returns. This means it must free the medium after it has been used by calling the ReleaseStgMedium function. If FALSE, the caller retains ownership of the storage medium and the data object called uses the storage medium for the duration of the call only. This method returns S_OK on success. Other possible values include the following. This doc was truncated. SetData allows another object to attempt to send data to the implementing data object. A data object implements this method if it supports receiving data from another object. If it does not support this, it should be implemented to return E_NOTIMPL. The caller allocates the storage medium indicated by the pmedium parameter, in which the data is passed. The data object called does not take ownership of the data until it has successfully received it and no error code is returned. The value of the fRelease parameter indicates the ownership of the medium after the call returns. FALSE indicates the caller still owns the medium, and the data object only has the use of it during the call; TRUE indicates that the data object now owns it and must release it when it is no longer needed. The type of medium specified in the pformatetc and pmedium parameters must be the same. For example, one cannot be a global handle and the other a stream. Read more on docs.microsoft.com. Creates an object to enumerate the formats supported by a data object. The direction of the data. Possible values come from the DATADIR enumeration. The value DATADIR_GET enumerates the formats that can be passed in to a call to IDataObject::GetData. The value DATADIR_SET enumerates those formats that can be passed in to a call to IDataObject::SetData. Read more on docs.microsoft.com. A pointer to an IEnumFORMATETC pointer variable that receives the interface pointer to the new enumerator object. This method returns S_OK on success. Other possible values include the following. This doc was truncated. EnumFormatEtc creates an enumerator object that can be used to determine all of the ways the data object can describe data in a FORMATETC structure, and provides a pointer to its IEnumFORMATETC interface. This is one of the standard enumerator interfaces.

Notes to Callers

Having obtained the pointer, the caller can enumerate the FORMATETC structures by calling the enumeration methods of IEnumFORMATETC. Because the formats can change over time, there is no guarantee that an enumerated format is currently supported because the formats can change over time. Accordingly, applications should treat the enumeration as a hint of the format types that can be passed. The caller is responsible for calling Release when it is finished with the enumerator. EnumFormatEtc is called when one of the following actions occurs: This doc was truncated. Read more on docs.microsoft.com. Called by an object supporting an advise sink to create a connection between a data object and the advise sink. This enables the advise sink to be notified of changes in the data of the object. A pointer to a FORMATETC structure that defines the format, target device, aspect, and medium that will be used for future notifications. For example, one sink may want to know only when the bitmap representation of the data in the data object changes. Another sink may be interested in only the metafile format of the same object. Each advise sink is notified when the data of interest changes. This data is passed back to the advise sink when notification occurs. A group of flags for controlling the advisory connection. Possible values are from the ADVF enumeration. However, only some of the possible ADVF values are relevant for this method. The following table briefly describes the relevant values. This doc was truncated. Read more on docs.microsoft.com. A pointer to the IAdviseSink interface on the advisory sink that will receive the change notification. A token that identifies this connection. You can use this token later to delete the advisory connection (by passing it to IDataObject::DUnadvise). If this value is 0, the connection was not established. This method returns S_OK on success. Other possible values include the following. This doc was truncated. DAdvise creates a change notification connection between a data object and the caller. The caller provides an advisory sink to which the notifications can be sent when the object's data changes. Objects used simply for data transfer typically do not support advisory notifications and return OLE_E_ADVISENOTSUPPORTED from DAdvise.

Notes to Callers

The object supporting the advise sink calls DAdvise to set up the connection, specifying the format, aspect, medium, and/or target device of interest in the FORMATETC structure passed in. If the data object does not support one or more of the requested attributes or the sending of notifications at all, it can refuse the connection by returning OLE_E_ADVISENOTSUPPORTED. Containers of linked objects can set up advisory connections directly with the bound link source or indirectly through the standard OLE link object that manages the connection. Connections set up with the bound link source are not automatically deleted. The container must explicitly call IDataObject::DUnadvise on the bound link source to delete an advisory connection. The OLE link object, manipulated through the IOleLink interface, is implemented in the default handler. Connections set up through the OLE link object are destroyed when the link object is deleted. The OLE default link object creates a "wildcard advise" with the link source so OLE can maintain the time of last change. This advise is specifically used to note the time that anything changed. OLE ignores all data formats that may have changed, noting only the time of last change. To allow wildcard advises, set the FORMATETC members as follows before calling DAdvise: This doc was truncated. Read more on docs.microsoft.com. Destroys a notification connection that had been previously set up. A token that specifies the connection to be removed. Use the value returned by IDataObject::DAdvise when the connection was originally established. This method returns S_OK on success. Other possible values include the following. This doc was truncated. This methods destroys a notification created with a call to the IDataObject::DAdvise method. If the advisory connection being deleted was initially set up by delegating the IDataObject::DAdvise call to IDataAdviseHolder::Advise, you must delegate this call to IDataAdviseHolder::Unadvise to delete it. Read more on docs.microsoft.com. Creates an object that can be used to enumerate the current advisory connections. A pointer to an IEnumSTATDATA pointer variable that receives the interface pointer to the new enumerator object. If the implementation sets *ppenumAdvise to NULL, there are no connections to advise sinks at this time. This method returns S_OK if the enumerator object is successfully instantiated or there are no connections. Other possible values include the following. This doc was truncated. The enumerator object created by this method implements the IEnumSTATDATA interface. IEnumSTATDATA permits the enumeration of the data stored in an array of STATDATA structures. Each of these structures provides information on a single advisory connection, and includes FORMATETC and ADVF information, as well as the pointer to the advise sink and the token representing the connection.

Notes to Callers

It is recommended that you use the OLE data advise holder object to handle advisory connections. With the pointer obtained through a call to CreateDataAdviseHolder, implementing IDataObject::EnumDAdvise becomes a simple matter of delegating the call to IDataAdviseHolder::EnumAdvise. This creates the enumerator and supplies the pointer to the OLE implementation of IEnumSTATDATA. At that point, you can call its methods to enumerate the current advisory connections. Read more on docs.microsoft.com. The IID guid for this interface. {0000010e-0000-0000-c000-000000000046} Retrieves the specified number of items in the enumeration sequence. (IEnumFORMATETC.Next) 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. Read more on docs.microsoft.com. 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. Learn more about this API from docs.microsoft.com. Skips over the specified number of items in the enumeration sequence. (IEnumFORMATETC.Skip) 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. Learn more about this API from docs.microsoft.com. Resets the enumeration sequence to the beginning. (IEnumFORMATETC.Reset) This method returns S_OK on success. 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. Creates a new enumerator that contains the same enumeration state as the current one. (IEnumFORMATETC.Clone) Address of an IEnumFORMATETC pointer variable that receives the interface pointer to the enumeration object. If the method is unsuccessful, the value of this output variable is undefined. This method returns S_OK on success. Other possible values include the following. This doc was truncated. Learn more about this API from docs.microsoft.com. The IID guid for this interface. {00000103-0000-0000-c000-000000000046} Retrieves the specified number of items in the enumeration sequence. (IEnumMoniker.Next) 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 calling AddRef, and the caller is responsible for calling Release through each pointer enumerated. 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. Read more on docs.microsoft.com. 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. Learn more about this API from docs.microsoft.com. Skips over the specified number of items in the enumeration sequence. (IEnumMoniker.Skip) 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. Learn more about this API from docs.microsoft.com. Resets the enumeration sequence to the beginning. (IEnumMoniker.Reset) This method returns S_OK on success. 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. Creates a new enumerator that contains the same enumeration state as the current one. (IEnumMoniker.Clone) Address of an IEnumMoniker pointer variable that receives the interface pointer to the enumeration object. If the method is unsuccessful, the value of this output variable is undefined. This method returns S_OK on success. Other possible values include the following. This doc was truncated. Learn more about this API from docs.microsoft.com. The IID guid for this interface. {00000102-0000-0000-c000-000000000046} Retrieves the specified number of items in the enumeration sequence. (IEnumSTATDATA.Next) 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. Read more on docs.microsoft.com. 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. Learn more about this API from docs.microsoft.com. Skips over the specified number of items in the enumeration sequence. (IEnumSTATDATA.Skip) 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. Learn more about this API from docs.microsoft.com. Resets the enumeration sequence to the beginning. (IEnumSTATDATA.Reset) This method returns S_OK on success. 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. Creates a new enumerator that contains the same enumeration state as the current one. (IEnumSTATDATA.Clone) A pointer to an IEnumSTATDATA pointer variable that receives the interface pointer to the enumeration object. If the method is unsuccessful, the value of this output variable is undefined. This method returns S_OK on success. Other possible values include the following. This doc was truncated. Learn more about this API from docs.microsoft.com. The IID guid for this interface. {00000105-0000-0000-c000-000000000046} The IEnumString::Next (objidlbase.h) method 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. Read more on docs.microsoft.com. The number of items that were retrieved. This parameter is always less than or equal to the number of items requested. If the method retrieves the number of items requested, the return value is S_OK. Otherwise, it is S_FALSE. Learn more about this API from docs.microsoft.com. The IEnumString::Skip (objidlbase.h) method 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. Learn more about this API from docs.microsoft.com. The IEnumString::Reset (objidlbase.h) method resets the enumeration sequence to the beginning. The return value is S_OK. 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. The IEnumString::Clone (objidlbase.h) method creates a new enumerator that contains the same enumeration state as the current one. A pointer to the cloned enumerator object. This method can return the standard return values E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED, and S_OK. Learn more about this API from docs.microsoft.com. The IID guid for this interface. {00000101-0000-0000-c000-000000000046} The IEnumUnknown::Next (objidlbase.h) method 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 calling AddRef, and the caller is responsible for calling Release through each pointer enumerated. 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. Read more on docs.microsoft.com. The number of items that were retrieved. This parameter is always less than or equal to the number of items requested. If the method retrieves the number of items requested, the return value is S_OK. Otherwise, it is S_FALSE. Learn more about this API from docs.microsoft.com. The IEnumUnknown::Skip (objidlbase.h) method 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. Learn more about this API from docs.microsoft.com. The IEnumUnknown::Reset (objidlbase.h) method resets the enumeration sequence to the beginning. The return value is S_OK. 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. The IEnumUnknown::Clone (objidlbase.h) method creates a new enumerator that contains the same enumeration state as the current one. A pointer to the cloned enumerator object. This method can return the standard return values E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED, and S_OK. Learn more about this API from docs.microsoft.com. The IID guid for this interface. {00000100-0000-0000-c000-000000000046} Registers the specified interface on an object residing in one apartment of a process as a global interface, enabling other apartments access to that interface. An interface pointer of type riid on the object on which the interface to be registered as global is implemented. The IID of the interface to be registered as global. An identifier that can be used by another apartment to get access to a pointer to the interface being registered. The value of an invalid cookie is 0. This method can return the following values. This doc was truncated. Called in the apartment in which an object resides to register one of the object's interfaces as a global interface. This method supplies a pointer to a cookie that other apartments can use in a call to the GetInterfaceFromGlobal method to get a pointer to that interface. The interface pointer may be a pointer to an in-process object, or it may be a pointer to a proxy for an object residing in another apartment, in another process, or on another computer. The apartment that calls this method must remain alive until the corresponding call to RevokeInterfaceFromGlobal. Read more on docs.microsoft.com. Revokes the registration of an interface in the global interface table. Identifies the interface whose global registration is to be revoked. This method can return the following values. This doc was truncated. Call this method when an interface registered in the global interface table object no longer needs to be accessed by other apartments in the same process. This method can be called by any apartment in the process, including apartments other than the one that registered the interface in the global interface table. Retrieves a pointer to an interface on an object that is usable by the calling apartment. This interface must be currently registered in the global interface table. Identifies the interface (and its object), and is retrieved through a call to IGlobalInterfaceTable::RegisterInterfaceInGlobal. The IID of the interface. A pointer to the pointer for the requested interface. This method can return the following values. This doc was truncated. After an interface has been registered in the global interface table, an apartment can get a pointer to this interface by calling the GetInterfaceFromGlobal method with the supplied cookie. This pointer to the interface can be used in the calling apartment but not by other apartments in the process. The application is responsible for coordinating access to the global variable during calls to IGlobalInterfaceTable::RevokeInterfaceFromGlobal. That is, the application should ensure that one thread does not call RevokeInterfaceFromGlobal while another thread is calling GetInterfaceFromGlobal with the same cookie. Multiple calls to GetInterfaceFromGlobal for the same cookie are permitted. The GetInterfaceFromGlobal method calls AddRef on the pointer obtained in the ppv parameter. It is the caller's responsibility to call Release on this pointer. Read more on docs.microsoft.com. The IID guid for this interface. {00000146-0000-0000-c000-000000000046} Binds to the specified object. The binding process involves finding the object, putting it into the running state if necessary, and providing the caller with a pointer to a specified interface on the identified object. A pointer to the IBindCtx interface on the bind context object, which is used in this binding operation. 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 moniker implementation should retrieve information about its environment. If the moniker is part of a composite moniker, pointer to the moniker to the left of this moniker. This parameter is primarily used by moniker implementers to enable cooperation between the various components of a composite moniker. Moniker clients should use NULL. The IID of the interface the client wishes to use to communicate with the object that the moniker identifies. The address of pointer variable that receives the interface pointer requested in riid. Upon successful return, *ppvResult contains the requested interface pointer to the object the moniker identifies. When successful, the implementation must call AddRef on the moniker. It is the caller's responsibility to call Release. If an error occurs, *ppvResult should be NULL. This method can return the standard return values E_OUTOFMEMORY and E_UNEXPECTED, as well as the following values. This doc was truncated. BindToObject implements the primary function of a moniker, which is to locate the object identified by the moniker and return a pointer to one of its interfaces.

Notes to Callers

If you are using a moniker as a persistent connection between two objects, you activate the connection by calling BindToObject. You typically call BindToObject during the following process: This doc was truncated. Read more on docs.microsoft.com. Binds to the storage for the specified object. Unlike the IMoniker::BindToObject method, this method does not activate the object identified by the moniker. A pointer to the IBindCtx interface on the bind context object, which is used in this binding operation. 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 moniker implementation should retrieve information about its environment. If the moniker is part of a composite moniker, pointer to the moniker to the left of this moniker. This parameter is primarily used by moniker implementers to enable cooperation between the various components of a composite moniker. Moniker clients should use NULL. A reference to the identifier of the storage interface requested, whose pointer will be returned in ppvObj. Storage interfaces commonly requested include IStorage, IStream, and ILockBytes. The address of pointer variable that receives the interface pointer requested in riid. Upon successful return, *ppvObj contains the requested interface pointer to the storage of the object the moniker identifies. When successful, the implementation must call AddRef on the storage. It is the caller's responsibility to call Release. If an error occurs, *ppvObj should be NULL. This method can return the standard return values E_UNEXPECTED, as well as the following values. This doc was truncated. There is an important difference between the BindToObject and BindToStorage methods. If, for example, you have a moniker that identifies a spreadsheet object, calling BindToObject provides access to the spreadsheet object itself, while calling BindToStorage provides access to the storage object in which the spreadsheet resides.

Notes to Callers

Although none of the COM moniker classes call this method in their binding operations, it might be appropriate to call it in the implementation of a new moniker class. You could call this method in an implementation of BindToObject that requires information from the object identified by the pmkToLeft parameter and can get it from the persistent storage of the object without activation. For example, if your monikers are used to identify objects that can be activated without activating their containers, you may find this method useful. A client that can read the storage of the object its moniker identifies could also call this method.

Notes to Implementers

Your implementation should locate the persistent storage for the object identified by the current moniker and return the desired interface pointer. Some types of monikers represent pseudo-objects, which are objects that do not have their own persistent storage. Such objects comprise some portion of the internal state of its container, for example, a range of cells in a spreadsheet. If your moniker class identifies this type of object, your implementation of BindToStorage should return the error MK_E_NOSTORAGE. If the bind context's BIND_OPTS structure specifies the BINDFLAGS_JUSTTESTEXISTENCE flag, your implementation has the option of returning NULL in ppvObj (although you can also ignore the flag and perform the complete binding operation).

Implementation-specific Notes

 This doc was truncated. Read more on docs.microsoft.com. Reduces a moniker to its simplest form. A pointer to the IBindCtx interface on the bind context to be used in this binding operation. 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 moniker implementation should retrieve information about its environment. Specifies how far this moniker should be reduced. This parameter must be one of the values from the MKRREDUCE enumeration. On entry, a pointer to an IMoniker pointer variable that contains the interface pointer to moniker to the left of this moniker. This parameter is used primarily by moniker implementers to enable cooperation between the various components of a composite moniker; moniker clients can usually pass NULL. On return, *ppmkToLeft is usually set to NULL, indicating no change in the original moniker to the left. In rare situations, *ppmkToLeft indicates a moniker, indicating that the previous moniker to the left should be disregarded and the moniker returned through *ppmkToLeft is the replacement. In such a situation, the implementation must call Release on the old moniker to the left of this moniker and must call AddRef on the new returned moniker; the caller must release it later. If an error occurs, the implementation can either leave the interface pointer unchanged or set it to NULL. Read more on docs.microsoft.com. A pointer to an IMoniker pointer variable that receives the interface pointer to the reduced form of this moniker, which can be NULL if an error occurs or if this moniker is reduced to nothing. If this moniker cannot be reduced, *ppmkReduced is simply set to this moniker and the return value is MK_S_REDUCED_TO_SELF. If *ppmkReduced is non-NULL, the implementation must call AddRef on the new moniker; it is the caller's responsibility to call Release. (This is true even if *ppmkReduced is set to this moniker.) This method can return the standard return values E_OUTOFMEMORY and E_UNEXPECTED, as well as the following values. This doc was truncated. This method is intended for the following uses: This doc was truncated. Read more on docs.microsoft.com. Creates a new composite moniker by combining the current moniker with the specified moniker. A pointer to the IMoniker interface on the moniker to compose onto the end of this moniker. If TRUE, the caller requires a nongeneric composition, so the operation should proceed only if pmkRight is a moniker class that this moniker can compose with in some way other than forming a generic composite. If FALSE, the method can create a generic composite if necessary. Most callers should set this parameter to FALSE. A pointer to an IMoniker pointer variable that receives the composite moniker pointer. When successful, the implementation must call AddRef on the resulting moniker; it is the caller's responsibility to call Release. If an error occurs or if the monikers compose to nothing (for example, composing an anti-moniker with an item moniker or a file moniker), *ppmkComposite should be set to NULL. This method can return the standard return values E_OUTOFMEMORY and E_UNEXPECTED, as well as the following values. This doc was truncated. Joining two monikers together is called composition. Sometimes two monikers of the same class can be combined in what is called nongeneric composition. For example, a file moniker representing an incomplete path and another file moniker representing a relative path can be combined to form a single file moniker representing the complete path. Nongeneric composition for a given moniker class can be handled only in the implementation of ComposeWith for that moniker class. Combining two monikers of any class is called generic composition, which can be accomplished through a call to the CreateGenericComposite function. Composition of monikers is an associative operation. That is, if A, B, and C are monikers, then, where Comp() represents the composition operation, Comp( Comp( A, B ), C ) is always equal to Comp( A, Comp( B, C ) ).

Notes to Callers

To combine two monikers, you should call ComposeWith rather than calling the CreateGenericComposite function to give the first moniker a chance to perform a nongeneric composition. An object that provides item monikers to identify its objects would call ComposeWith to provide a moniker that completely identifies the location of the object. This would apply, for example, to a server that supports linking to portions of a document, or to a container that supports linking to embedded objects within its documents. In such a situation, you would do the following: This doc was truncated. Read more on docs.microsoft.com. Retrieves a pointer to an enumerator for the components of a composite moniker. If TRUE, enumerates the monikers from left to right. If FALSE, enumerates from right to left. A pointer to an IEnumMoniker pointer variable that receives the interface pointer to the enumerator object for the moniker. When successful, the implementation must call AddRef on the enumerator object. It is the caller's responsibility to call Release. If an error occurs or if the moniker has no enumerable components, the implementation sets *ppenumMoniker to NULL. This method can return the standard return values E_OUTOFMEMORY, E_UNEXPECTED, and S_OK. This method must supply an IEnumMoniker pointer to an enumerator that can enumerate the components of a moniker. For example, the implementation of the IMoniker::Enum method for a generic composite moniker creates an enumerator that can determine the individual monikers that make up the composite, while the IMoniker::Enum method for a file moniker creates an enumerator that returns monikers representing each of the components in the path.

Notes to Callers

Call this method to examine the components that make up a composite moniker.

Notes to Implementers

If the new moniker class has no discernible internal structure, your implementation of this method can simply return S_OK and set ppenumMoniker to NULL.

Implementation-specific Notes

 This doc was truncated. Read more on docs.microsoft.com. Determines whether this moniker is identical to the specified moniker. A pointer to the IMoniker interface on the moniker to be used for comparison with this one (the one from which this method is called). This method returns S_OK to indicate that the two monikers are identical, and S_FALSE otherwise. Previous implementations of the running object table (ROT) called this method. The current implementation of the ROT uses the IROTData interface instead.

Notes to Callers

Call this method to determine whether two monikers are identical. The reduced form of a moniker is considered different from the unreduced form. You should call the IMoniker::Reduce method before calling IsEqual, because a reduced moniker is in its most specific form. IsEqual may return S_FALSE on two monikers before they are reduced, and S_OK after they are reduced.

Notes to Implementers

Your implementation should not reduce the current moniker before performing the comparison. It is the caller's responsibility to call IMoniker::Reduce to compare reduced monikers. Two monikers that compare as equal must hash to the same value using IMoniker::Hash.

Implementation-specific Notes

 This doc was truncated. Read more on docs.microsoft.com. Creates a hash value using the internal state of the moniker. A pointer to a variable that receives the hash value. This method returns S_OK to indicate that the hash value was retrieved successfully.

Notes to Callers

You can use the value returned by this method to maintain a hash table of monikers. The hash value determines a hash bucket in the table. To search such a table for a specified moniker, calculate its hash value and then compare it to the monikers in that hash bucket using IMoniker::IsEqual.

Notes to Implementers

The hash value must be constant for the lifetime of the moniker. Two monikers that compare as equal using IMoniker::IsEqual must hash to the same value. Marshaling and then unmarshaling a moniker should have no effect on its hash value. Consequently, your implementation of IMoniker::Hash should rely only on the internal state of the moniker, not on its memory address.

Implementation-specific Notes

 This doc was truncated. Read more on docs.microsoft.com. Determines whether the object identified by this moniker is currently loaded and running. A pointer to the IBindCtx interface on the bind context to be used in this binding operation. 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 moniker implementation should retrieve information about its environment. A pointer to the IMoniker interface on the moniker to the left of this moniker if this moniker is part of a composite. This parameter is used primarily by moniker implementers to enable cooperation between the various components of a composite moniker; moniker clients can usually pass NULL. A pointer to the IMoniker interface on the moniker most recently added to the running object table (ROT). This can be NULL. If non-NULL, the implementation can return the results of calling IMoniker::IsEqual on the pmkNewlyRunning parameter, passing the current moniker. This parameter is intended to enable IsRunning implementations that are more efficient than just searching the ROT, but the implementation can choose to ignore pmkNewlyRunning without causing any harm. This method can return the standard return values E_UNEXPECTED, as well as the following values. This doc was truncated.

Notes to Callers

If speed is important when you're requesting services from the object identified by the moniker, you may want those services only if the object is already running (because loading an object into the running state may be time-consuming). In such a situation, you should call IsRunning to determine whether the object is running. For the monikers stored within linked objects, IsRunning is primarily called by the default handler's implementation of IOleLink::BindIfRunning.

Notes to Implementers

To get a pointer to the ROT, your implementation should call IBindCtx::GetRunningObjectTable on the pbc parameter. Your implementation can then call IRunningObjectTable::IsRunning to determine whether the object identified by the moniker is running. The object identified by the moniker must have registered itself with the ROT when it first began running.

Implementation-specific Notes

 This doc was truncated. Read more on docs.microsoft.com. Retrieves the time at which the object identified by this moniker was last changed. A pointer to the bind context to be used in this binding operation. 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 moniker implementation should retrieve information about its environment. For more information, see IBindCtx. If the moniker is part of a composite moniker, pointer to the moniker to the left of this moniker. This parameter is primarily used by moniker implementers to enable cooperation between the various components of a composite moniker. Moniker clients should pass NULL. A pointer to the FILETIME structure that receives the time of last change. A value of {0xFFFFFFFF,0x7FFFFFFF} indicates an error (for example, exceeded time limit, information not available). This method can return the standard return values E_OUTOFMEMORY, as well as the following values. This doc was truncated. To be precise, the time returned is the earliest time COM can identify after which no change has occurred, so this time may be later than the time of the last change to the object.

Notes to Callers

If you're caching information returned by the object identified by the moniker, you may want to ensure that your information is up-to-date. To do so, you would call GetTimeOfLastChange and compare the time returned with the time you last retrieved information from the object. For the monikers stored within linked objects, GetTimeOfLastChange is primarily called by the default handler's implementation of IOleObject::IsUpToDate. Container applications call IOleObject::IsUpToDate to determine if a linked object (or an embedded object containing linked objects) is up-to-date without actually binding to the object. This enables an application to determine quickly which linked objects require updating when the end user opens a document. The application can then bind only those linked objects that need updating (after prompting the end user to determine whether they should be updated) instead of binding every linked object in the document.

Notes to Implementers

It is important to perform this operation quickly because, for linked objects, this method is called when a user first opens a compound document. Consequently, your GetTimeOfLastChange implementation should not bind to any objects. In addition, your implementation should check the deadline parameter in the bind context and return MK_E_EXCEEDEDDEADLINE if the operation cannot be completed by the specified time. Following are some strategies you can use in your implementations: This doc was truncated. Read more on docs.microsoft.com. Creates a moniker that is the inverse of this moniker. When composed to the right of this moniker or one of similar structure, the moniker will compose to nothing. The address of an IMoniker pointer variable that receives the interface pointer to a moniker that is the inverse of this moniker. When successful, the implementation must call AddRef on the new inverse moniker. It is the caller's responsibility to call Release. If an error occurs, the implementation should set *ppmk to NULL. This method can return the standard return values E_OUTOFMEMORY, as well as the following values. This doc was truncated. The inverse of a moniker is analogous to the ".." directory in MS-DOS file systems; the ".." directory acts as the inverse to any other directory name, because appending ".." to a directory name results in an empty path. In the same way, the inverse of a moniker typically is also the inverse of all monikers in the same class. However, it is not necessarily the inverse of a moniker of a different class. The inverse of a composite moniker is a composite consisting of the inverses of the components of the original moniker, arranged in reverse order. For example, if the inverse of A is Inv( A ) and the composite of A, B, and C is Comp( A, B, C ), then Inv( Comp( A, B, C ) ) is equal to Comp( Inv( C ), Inv( B ), Inv( A ) ). Not all monikers have inverses. Most monikers that are themselves inverses, such as anti-monikers, do not have inverses. Monikers that have no inverse cannot have relative monikers formed from inside the objects they identify to other objects outside.

Notes to Callers

An object that is using a moniker to locate another object usually does not know the class of the moniker it is using. To get the inverse of a moniker, you should always call IMoniker::Inverse rather than the CreateAntiMoniker function, because you cannot be certain that the moniker you're using considers an anti-moniker to be its inverse. The Inverse method is also called by the implementation of the IMoniker::RelativePathTo method, to assist in constructing a relative moniker.

Notes to Implementers

If your monikers have no internal structure, you can call the CreateAntiMoniker function in to get an anti-moniker in your implementation of IMoniker::Inverse. In your implementation of IMoniker::ComposeWith, you need to check for the inverse you supply in the implementation of Inverse.

Implementation-specific Notes

 This doc was truncated. Read more on docs.microsoft.com. Creates a new moniker based on the prefix that this moniker has in common with the specified moniker. A pointer to the IMoniker interface on another moniker to be compared with this one to determine whether there is a common prefix. The address of an IMoniker* pointer variable that receives the interface pointer to the moniker that is the common prefix of this moniker and pmkOther. When successful, the implementation must call AddRef on the resulting moniker; it is the caller's responsibility to call Release. If an error occurs or if there is no common prefix, the implementation should set *ppmkPrefix to NULL. This method can return the standard return values E_OUTOFMEMORY, as well as the following values. This doc was truncated. CommonPrefixWith creates a new moniker that consists of the common prefixes of the moniker on this moniker object and another moniker. For example, if one moniker represents the path "c:\projects\secret\art\pict1.bmp" and another moniker represents the path "c:\projects\secret\docs\chap1.txt", the common prefix of these two monikers would be a moniker representing the path "c:\projects\secret".

Notes to Callers

The CommonPrefixWith method is primarily called in the implementation of the IMoniker::RelativePathTo method. Clients using a moniker to locate an object rarely need to call this method. Call this method only if pmkOther and this moniker are both absolute monikers. An absolute moniker is either a file moniker or a generic composite whose leftmost component is a file moniker that represents an absolute path. Do not call this method on relative monikers because it would not produce meaningful results.

Notes to Implementers

Your implementation should first determine whether pmkOther is a moniker of a class that you recognize and for which you can provide special handling (for example, if it is of the same class as this moniker). If so, your implementation should determine the common prefix of the two monikers. Otherwise, it should pass both monikers in a call to the MonikerCommonPrefixWith function, which correctly handles the generic case.

Implementation-specific Notes

 This doc was truncated. Read more on docs.microsoft.com. Creates a relative moniker between this moniker and the specified moniker. A pointer to the IMoniker interface on the moniker to which a relative path should be taken. A pointer to an IMoniker pointer variable that receives the interface pointer to the relative moniker. When successful, the implementation must call AddRef on the new moniker; it is the caller's responsibility to call Release. If an error occurs, the implementation sets *ppmkRelPath to NULL. This method can return the standard return values E_OUTOFMEMORY and E_UNEXPECTED, as well as the following values. This doc was truncated. A relative moniker is analogous to a relative path (such as "..\backup"). For example, suppose you have one moniker that represents the path "c:\projects\secret\art\pict1.bmp" and another moniker that represents the path "c:\projects\secret\docs\chap1.txt". Calling RelativePathTo on the first moniker, passing the second one as the pmkOther parameter, would create a relative moniker representing the path "..\docs\chap1.txt".

Notes to Callers

Moniker clients typically do not need to call RelativePathTo. This method is called primarily by the default handler for linked objects. Linked objects contain both an absolute and a relative moniker to identify the link source. (This enables link tracking if the user moves a directory tree containing both the container and source files.) The default handler calls this method to create a relative moniker from the container document to the link source. (That is, it calls RelativePathTo on the moniker identifying the container document, passing the moniker identifying the link source as the pmkOther parameter.) If you do call RelativePathTo, call it only on absolute monikers, for example, a file moniker or a composite moniker whose leftmost component is a file moniker, where the file moniker represents an absolute path. Do not call this method on relative monikers.

Notes to Implementers

Your implementation of RelativePathTo should first determine whether pmkOther is a moniker of a class that you recognize and for which you can provide special handling (for example, if it is of the same class as this moniker). If so, your implementation should determine the relative path. Otherwise, it should pass both monikers in a call to the MonikerRelativePathTo function, which correctly handles the generic case. The first step in determining a relative path is determining the common prefix of this moniker and pmkOther. The next step is to break this moniker and pmkOther into two parts each, say (P, myTail) and (P, otherTail) respectively, where P is the common prefix. The correct relative path is then the inverse of myTail composed with otherTail: Comp( Inv( myTail ), otherTail ) where Comp() represents the composition operation and Inv() represents the inverse operation. For certain types of monikers, you cannot use your IMoniker::Inverse method to construct the inverse of myTail. For example, a file moniker returns an anti-moniker as an inverse, while its RelativePathTo method must use one or more file monikers that each represent the path ".." to construct the inverse of myTail.

Implementation-specific Notes

 This doc was truncated. Read more on docs.microsoft.com. Retrieves the display name for the moniker. A pointer to the IBindCtx interface on the bind context to be used in this operation. 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 moniker implementation should retrieve information about its environment. If the moniker is part of a composite moniker, pointer to the moniker to the left of this moniker. This parameter is used primarily by moniker implementers to enable cooperation between the various components of a composite moniker. Moniker clients should pass NULL. The address of a pointer variable that receives a pointer to the display name string for the moniker. 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 the caller and the implementation of this method use the COM task allocator returned by CoGetMalloc. If an error occurs, the implementation must set *ppszDisplayName should be set to NULL. This method can return the standard return values E_OUTOFMEMORY, as well as the following values. This doc was truncated. GetDisplayName provides a string that is a displayable representation of the moniker. A display name is not a complete representation of a moniker's internal state; it is simply a form that can be read by users. As a result, it is possible (though rare) for two different monikers to have the same display name. While there is no guarantee that the display name of a moniker can be parsed back into that moniker when calling the MkParseDisplayName function with it, failure to do so is rare.

Notes to Callers

It is possible that retrieving a moniker's display name may be an expensive operation. For efficiency, you may want to cache the results of the first successful call to GetDisplayName, rather than making repeated calls.

Notes to Implementers

If you are writing a moniker class in which the display name does not change, simply cache the display name and supply the cached name when requested. If the display name can change over time, getting the current display name might mean that the moniker has to access the object's storage or bind to the object, either of which can be expensive operations. If this is the case, your implementation of GetDisplayName should return MK_E_EXCEEDEDDEADLINE if the name cannot be retrieved by the time specified in the bind context's BIND_OPTS structure. A moniker that is intended to be part of a generic composite moniker should include any preceding delimiter (such as '\') as part of its display name. For example, the display name returned by an item moniker includes the delimiter specified when it was created with the CreateItemMoniker function. The display name for a file moniker does not include a delimiter because file monikers are always expected to be the leftmost component of a composite.

Implementation-specific Notes

 This doc was truncated. Read more on docs.microsoft.com. Converts a display name into a moniker. A pointer to the IBindCtx interface on the bind context to be used in this binding operation. 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 moniker implementation should retrieve information about its environment. A pointer to the IMoniker interface on the moniker that has been built out of the display name up to this point. The remaining display name to be parsed. A pointer to a variable that receives the number of characters in pszDisplayName that were consumed in this step. A pointer to an IMoniker pointer variable that receives the interface pointer to the moniker that was built from pszDisplayName. When successful, the implementation must call AddRef on the new moniker; it is the caller's responsibility to call Release. If an error occurs, the implementation sets *ppmkOut to NULL. This method can return the standard return valuesE_OUTOFMEMORY and E_UNEXPECTED, as well as the following values. This doc was truncated.

Notes to Callers

Moniker clients do not typically call ParseDisplayName directly. Instead, they call the MkParseDisplayName function when they want to convert a display name into a moniker (for example, in implementing the Links dialog box for a container application, or for implementing a macro language that supports references to objects outside the document). That function first parses the initial portion of the display name itself. It then calls ParseDisplayName on the moniker it has just created, passing the remainder of the display name and getting a new moniker in return; this step is repeated until the entire display name has been parsed.

Notes to Implementers

Your implementation may be able to perform this parsing by itself if your moniker class is designed to designate only certain kinds of objects. Otherwise, you must get an IParseDisplayName interface pointer for the object identified by the moniker-so-far (that is, the composition of pmkToLeft and this moniker) and then return the results of calling IParseDisplayName::ParseDisplayName. There are different strategies for getting an IParseDisplayName pointer, as follows: This doc was truncated. Read more on docs.microsoft.com. Determines whether this moniker is one of the system-provided moniker classes. A pointer to a variables that receives one of the values from the MKSYS enumeration and refers to one of the COM moniker classes. This parameter cannot be NULL. This method returns S_OK to indicate that the moniker is a system moniker, and S_FALSE otherwise.

Notes to Callers

New values of the MKSYS enumeration may be defined in the future; therefore, you should explicitly test for each value you are interested in.

Notes to Implementers

Your implementation of this method must return MKSYS_NONE. You cannot use this function to identify your own monikers (for example, in your implementation of IMoniker::ComposeWith). Instead, you should use your moniker's implementation of IPersist::GetClassID or use QueryInterface to test for your own private interface.

Implementation-specific Notes

 This doc was truncated. Read more on docs.microsoft.com. The IID guid for this interface. {0000000f-0000-0000-c000-000000000046} Specifies the way a function is invoked. In C, value assignment is written as *pobj1 = *pobj2, while reference assignment is written as pobj1 = pobj2. Other languages have other syntactic conventions. A property or data member can support only a value assignment, a reference assignment, or both. The INVOKEKIND enumeration constants are the same constants that are passed to IDispatch::Invoke to specify the way in which a function is invoked. The member is called using a normal function invocation syntax. The function is invoked using a normal property-access syntax. The function is invoked using a property value assignment syntax. Syntactically, a typical programming language might represent changing a property in the same way as assignment. For example: object.property : = value. The function is invoked using a property reference assignment syntax. Retrieves the class identifier (CLSID) of the object. A pointer to the location that receives the CLSID on return. The CLSID is a globally unique identifier (GUID) that uniquely represents an object class that defines the code that can manipulate the object's data. If the method succeeds, the return value is S_OK. Otherwise, it is E_FAIL. The GetClassID method retrieves the class identifier (CLSID) for an object, used in later operations to load object-specific code into the caller's context.

Notes to Callers

A container application might call this method to retrieve the original CLSID of an object that it is treating as a different class. Such a call would be necessary if a user performed an editing operation that required the object to be saved. If the container were to save it using the treat-as CLSID, the original application would no longer be able to edit the object. Typically, in this case, the container calls the OleSave helper function, which performs all the necessary steps. For this reason, most container applications have no need to call this method directly. The exception would be a container that provides an object handler for certain objects. In particular, a container application should not get an object's CLSID and then use it to retrieve class specific information from the registry. Instead, the container should use IOleObject and IDataObject interfaces to retrieve such class-specific information directly from the object.

Notes to Implementers

Typically, implementations of this method simply supply a constant CLSID for an object. If, however, the object's TreatAs registry key has been set by an application that supports emulation (and so is treating the object as one of a different class), a call to GetClassID must supply the CLSID specified in the TreatAs key. For more information on emulation, see CoTreatAsClass. When an object is in the running state, the default handler calls an implementation of GetClassID that delegates the call to the implementation in the object. When the object is not running, the default handler instead calls the ReadClassStg function to read the CLSID that is saved in the object's storage. If you are writing a custom object handler for your object, you might want to simply delegate this method to the default handler implementation (see OleCreateDefaultHandler).

URL Moniker Notes

This method returns CLSID_StdURLMoniker. Read more on docs.microsoft.com. The IID guid for this interface. {0000010c-0000-0000-c000-000000000046} Determines whether an object has changed since it was last saved to its stream. (IPersistStream.IsDirty) This method returns S_OK to indicate that the object has changed. Otherwise, it returns S_FALSE. Use this method to determine whether an object should be saved before closing it. The dirty flag for an object is conditionally cleared in the IPersistStream::Save method.

Notes to Callers

You should treat any error return codes as an indication that the object has changed. Unless this method explicitly returns S_FALSE, assume that the object must be saved. Note that the OLE-provided implementations of the IPersistStream::IsDirty method in the OLE-provided moniker interfaces always return S_FALSE because their internal state never changes. Read more on docs.microsoft.com. Initializes an object from the stream where it was saved previously. (IPersistStream.Load) An IStream pointer to the stream from which the object should be loaded. This method can return the following values. This doc was truncated. This method loads an object from its associated stream. The seek pointer is set as it was in the most recent IPersistStream::Save method. This method can seek and read from the stream, but cannot write to it.

Notes to Callers

Rather than calling IPersistStream::Load directly, you typically call the OleLoadFromStream function does the following: This doc was truncated. Read more on docs.microsoft.com. Saves an object to the specified stream. (IPersistStream.Save) An IStream pointer to the stream into which the object should be saved. Indicates whether to clear the dirty flag after the save is complete. If TRUE, the flag should be cleared. If FALSE, the flag should be left unchanged. This method can return the following values. This doc was truncated. IPersistStream::Save saves an object into the specified stream and indicates whether the object should reset its dirty flag. The seek pointer is positioned at the location in the stream at which the object should begin writing its data. The object calls the ISequentialStream::Write method to write its data. On exit, the seek pointer must be positioned immediately past the object data. The position of the seek pointer is undefined if an error returns.

Notes to Callers

Rather than calling IPersistStream::Save directly, you typically call the OleSaveToStream helper function which does the following: This doc was truncated. Read more on docs.microsoft.com. Retrieves the size of the stream needed to save the object. (IPersistStream.GetSizeMax) The size in bytes of the stream needed to save this object, in bytes. This method returns S_OK to indicate that the size was retrieved successfully. This method returns the size needed to save an object. You can call this method to determine the size and set the necessary buffers before calling the IPersistStream::Save method.

Notes to Implementers

The GetSizeMax implementation should return a conservative estimate of the necessary size because the caller might call the IPersistStream::Save method with a non-growable stream.

URL Moniker Notes

This method retrieves the maximum number of bytes in the stream that will be required by a subsequent call to IPersistStream::Save. This value is sizeof(ULONG)==4 plus sizeof(WCHAR)*n where n is the length of the full or partial URL string, including the NULL terminator. Read more on docs.microsoft.com. The IID guid for this interface. {00000109-0000-0000-c000-000000000046} Registers an object and its identifying moniker in the running object table (ROT). Specifies whether the ROT's reference to punkObject is weak or strong and controls access to the object through its entry in the ROT. For details, see the Remarks section. This doc was truncated. Read more on docs.microsoft.com. A pointer to the object that is being registered as running. A pointer to the moniker that identifies punkObject. An identifier for this ROT entry that can be used in subsequent calls to IRunningObjectTable::Revoke or IRunningObjectTable::NoteChangeTime. The caller cannot specify NULL for this parameter. If an error occurs, *pdwRegister is set to zero. This method can return the standard return values E_INVALIDARG and E_OUTOFMEMORY, as well as the following values. This doc was truncated. This method registers a pointer to an object under a moniker that identifies the object. The moniker is used as the key when the table is searched with IRunningObjectTable::GetObject. When an object is registered, the ROT always calls AddRef on the object. For a weak registration (ROTFLAGS_REGISTRATIONKEEPSALIVE not set), the ROT will release the object whenever the last strong reference to the object is released. For a strong registration (ROTFLAGS_REGISTRATIONKEEPSALIVE set), the ROT prevents the object from being destroyed until the object's registration is explicitly revoked. A server registered as either LocalService or RunAs can set the ROTFLAGS_ALLOWANYCLIENT flag in its call to Register to allow any client to connect to it. A server setting this bit must have its executable name in the AppID section of the registry that refers to the AppID for the executable. An "activate as activator" server (not registered as LocalService or RunAs) must not set this flag in its call to Register. For details on installing services, see Installing as a Service Application. Registering a second object with the same moniker, or re-registering the same object with the same moniker, creates a second entry in the ROT. In this case, Register returns MK_S_MONIKERALREADYREGISTERED. Each call to Register must be matched by a call to IRunningObjectTable::Revoke because even duplicate entries have different pdwRegister identifiers. A problem with duplicate registrations is that there is no way to determine which object will be returned if the moniker is specified in a subsequent call to IRunningObjectTable::IsRunning.

Notes to Callers

If you are a moniker provider (that is, you hand out monikers identifying your objects to make them accessible to others), you must call the Register method to register your objects when they begin running. You must also call this method if you rename your objects while they are loaded. The most common type of moniker provider is a compound-document link source. This includes server applications that support linking to their documents (or portions of a document) and container applications that support linking to embeddings within their documents. Server applications that do not support linking can also use the ROT to cooperate with container applications that support linking to embeddings. If you are writing a server application, you should register an object with the ROT when it begins running, typically in your implementation of IOleObject::DoVerb. The object must be registered under its full moniker, which requires getting the moniker of its container document using IOleClientSite::GetMoniker. You should also revoke and re-register the object in your implementation of IOleObject::SetMoniker, which is called if the container document is renamed. If you are writing a container application that supports linking to embeddings, you should register your document with the ROT when it is loaded. If your document is renamed, you should revoke and re-register it with the ROT and call IOleObject::SetMoniker for any embedded objects in the document to give them an opportunity to re-register themselves. Objects registered in the ROT must be explicitly revoked when the object is no longer running or when its moniker changes. This revocation is important because there is no way for the system to automatically remove entries from the ROT. You must cache the identifier that is written through pdwRegister and use it in a call to IRunningObjectTable::Revoke to revoke the registration. For a strong registration, a strong reference is released when the objects registration is revoked. As of Windows Server 2003, if there are stale entries that remain in the ROT due to unexpected server problems, COM will automatically remove these stale entries from the ROT. The system's implementation of Register calls IMoniker::Reduce on the pmkObjectName parameter to ensure that the moniker is fully reduced before registration. If an object is known by more than one fully reduced moniker, it should be registered under all such monikers. Read more on docs.microsoft.com. Removes an entry from the running object table (ROT) that was previously registered by a call to IRunningObjectTable::Register. The identifier of the ROT entry to be revoked. This method can return the standard return values E_INVALIDARG and S_OK. This method undoes the effect of a call to IRunningObjectTable::Register, removing both the moniker and the pointer to the object identified by that moniker.

Notes to Callers

A moniker provider (hands out monikers identifying its objects to make them accessible to others) must call the Revoke method to revoke the registration of its objects when it stops running. It must have previously called IRunningObjectTable::Register and stored the identifier returned by that method; it uses that identifier when calling Revoke. The most common type of moniker provider is a compound-document link source. This includes server applications that support linking to their documents (or portions of a document) and container applications that support linking to embeddings within their documents. Server applications that do not support linking can also use the ROT to cooperate with container applications that support linking to embeddings. If you are writing a container application, you must revoke a document's registration when the document is closed. You must also revoke a document's registration before re-registering it when it is renamed. If you are writing a server application, you must revoke an object's registration when the object is closed. You must also revoke an object's registration before re-registering it when its container document is renamed (see IOleObject::SetMoniker). Read more on docs.microsoft.com. Determines whether the object identified by the specified moniker is currently running. A pointer to the IMoniker interface on the moniker. If the object is in the running state, the return value is TRUE. Otherwise, it is FALSE. This method simply indicates whether a object is running. To retrieve a pointer to a running object, use the IRunningObjectTable::GetObject method.

Notes to Callers

Generally, you call the IsRunning method only if you are writing your own moniker class (that is, implementing the IMoniker interface). You typically call this method from your implementation of IMoniker::IsRunning. However, you should do so only if the pmkToLeft parameter of IMoniker::IsRunning is NULL. Otherwise, you should call IMoniker::IsRunning on your pmkToLeft parameter instead. Read more on docs.microsoft.com. Determines whether the object identified by the specified moniker is running, and if it is, retrieves a pointer to that object. A pointer to the IMoniker interface on the moniker. A pointer to an IUnknown pointer variable that receives the interface pointer to the running object. When successful, the implementation calls AddRef on the object; it is the caller's responsibility to call Release. If the object is not running or if an error occurs, the implementation sets *ppunkObject to NULL. This method can return the following values. This doc was truncated. This method checks the ROT for the moniker specified by pmkObjectName. If that moniker had previously been registered with a call to IRunningObjectTable::Register, this method returns the pointer that was registered at that time.

Notes to Callers

Generally, you call the IRunningObjectTable::GetObject method only if you are writing your own moniker class (that is, implementing the IMoniker interface). You typically call this method from your implementation of IMoniker::BindToObject. However, note that not all implementations of IMoniker::BindToObject need to call this method. If you expect your moniker to have a prefix (indicated by a non-NULLpmkToLeft parameter to IMoniker::BindToObject), you should not check the ROT. The reason for this is that only complete monikers are registered with the ROT, and if your moniker has a prefix, your moniker is part of a composite and thus not complete. Instead, your moniker should request services from the object identified by the prefix (for example, the container of the object identified by your moniker). Read more on docs.microsoft.com. Records the time that a running object was last modified. The object must have previously been registered with the running object table (ROT). This method stores the time of last change in the ROT. The identifier of the ROT entry of the changed object. This value was previously returned by IRunningObjectTable::Register. A pointer to a FILETIME structure containing the object's last change time. This method can return the standard return values E_INVALIDARG and S_OK. The time recorded by this method can be retrieved by calling IRunningObjectTable::GetTimeOfLastChange.

Notes to Callers

A moniker provider (hands out monikers identifying its objects to make them accessible to others) must call the NoteChangeTime method whenever its objects are modified. It must have previously called IRunningObjectTable::Register and stored the identifier returned by that method; it uses that identifier when calling NoteChangeTime. The most common type of moniker provider is a compound-document link source. This includes server applications that support linking to their documents (or portions of a document) and container applications that support linking to embeddings within their documents. Server applications that do not support linking can also use the ROT to cooperate with container applications that support linking to embeddings. When an object is first registered in the ROT, the ROT records its last change time as the value returned by calling IMoniker::GetTimeOfLastChange on the moniker being registered. Read more on docs.microsoft.com. Retrieves the time that an object was last modified. A pointer to the IMoniker interface on the moniker. A pointer to a FILETIME structure that receives the object's last change time. This method can return the following values. This doc was truncated. This method returns the change time that was last reported for this object by a call to IRunningObjectTable::NoteChangeTime. If NoteChangeTime has not been called previously, the method returns the time that was recorded when the object was registered. This method is provided to enable checking whether a connection between two objects (represented by one object holding a moniker that identifies the other) is up-to-date. For example, if one object is holding cached information about the other object, this method can be used to check whether the object has been modified since the cache was last updated. See IMoniker::GetTimeOfLastChange.

Notes to Callers

Generally, you call GetTimeOfLastChange only if you are writing your own moniker class (that is, implementing the IMoniker interface). You typically call this method from your implementation of IMoniker::GetTimeOfLastChange. However, you should do so only if the pmkToLeft parameter of IMoniker::GetTimeOfLastChange is NULL. Otherwise, you should call IMoniker::GetTimeOfLastChange on your pmkToLeft parameter instead. Read more on docs.microsoft.com. Creates and returns a pointer to an enumerator that can list the monikers of all the objects currently registered in the running object table (ROT). A pointer to an IEnumMoniker pointer variable that receives the interface pointer to the new enumerator for the ROT. When successful, the implementation calls AddRef on the enumerator; it is the caller's responsibility to call Release. If an error occurs; the implementation sets *ppenumMoniker to NULL. This method can return the standard return values E_OUTOFMEMORY and S_OK. IRunningObjectTable::EnumRunning must create and return a pointer to an IEnumMoniker interface on an enumerator object. The standard enumerator methods can then be called to enumerate the monikers currently registered in the registry. The enumerator cannot be used to enumerate monikers that are registered in the ROT after the enumerator has been created. The EnumRunning method is intended primarily for the use by the system in implementing the alert object table. Note that OLE 2 does not include an implementation of the alert object table. Read more on docs.microsoft.com. The IID guid for this interface. {00000010-0000-0000-c000-000000000046} Reads a specified number of bytes from the stream object into memory, starting at the current seek pointer. A pointer to the buffer which the stream data is read into. The number of bytes of data to read from the stream object. A pointer to a ULONG variable that receives the actual number of bytes read from the stream object.
Note  The number of bytes read may be zero.
 
 Read more on docs.microsoft.com. This method can return one of these values. | Return code | Description | |----------------|---------------| |S_OK | All of the requested data was successfully read from the stream object; the number of bytes requested in *cb* is the same as the number of bytes returned in *pcbRead*.| |S_FALSE | The value returned in *pcbRead* is less than the number of bytes requested in *cb*. This indicates the end of the stream has been reached. The number of bytes read indicates how much of the *pv* buffer has been filled.| |E_PENDING | Asynchronous storage only: Part or all of the data to be read is currently unavailable. | |STG_E_ACCESSDENIED | The caller does not have permissions required to read this stream object.| |STG_E_INVALIDPOINTER | One of the pointer values is invalid.| |STG_E_REVERTED | The object has been invalidated by a revert operation above it in the transaction tree.| This method reads bytes from this stream object into memory. The stream object must be opened in STGM_READ mode. This method adjusts the seek pointer by the actual number of bytes read. The number of bytes actually read is also returned in the pcbRead parameter.

Notes to Callers

The actual number of bytes read can be less than the number of bytes requested if an error occurs or if the end of the stream is reached during the read operation. The number of bytes returned should always be compared to the number of bytes requested. If the number of bytes returned is less than the number of bytes requested, it usually means the Read method attempted to read past the end of the stream. The application should handle both a returned error and S_OK return values on end-of-stream read operations. Read more on docs.microsoft.com. Writes a specified number of bytes into the stream object starting at the current seek pointer. A pointer to the buffer that contains the data that is to be written to the stream. A valid pointer must be provided for this parameter even when cb is zero. The number of bytes of data to attempt to write into the stream. This value can be zero. A pointer to a ULONG variable where this method writes the actual number of bytes written to the stream object. The caller can set this pointer to NULL, in which case this method does not provide the actual number of bytes written. This method can return one of these values. | Return code | Description | |----------------|---------------| |S_OK | The data was successfully written to the stream object.| |E_PENDING | Asynchronous Storage only: Part or all of the data to be written is currently unavailable.| |STG_E_MEDIUMFULL | The write operation failed because there is no space left on the storage device.| |STG_E_ACCESSDENIED | The caller does not have the required permissions for writing to this stream object.| |STG_E_CANTSAVE | Data cannot be written for reasons other than improper access or insufficient space.| |STG_E_INVALIDPOINTER | One of the pointer values is not valid. The *pv* parameter must contain a valid pointer even if *cb* is zero.| |STG_E_REVERTED | The object has been invalidated by a revert operation above it in the transaction tree.| |STG_E_WRITEFAULT | The write operation failed due to a disk error. This value is also returned when this method attempts to write to a stream that was opened in simple mode (using the STGM_SIMPLE flag).| ISequentialStream::Write writes the specified data to a stream object. The seek pointer is adjusted for the number of bytes actually written. The number of bytes actually written is returned in the pcbWritten parameter. If the byte count is zero bytes, the write operation has no effect. If the seek pointer is currently past the end of the stream and the byte count is nonzero, this method increases the size of the stream to the seek pointer and writes the specified bytes starting at the seek pointer. The fill bytes written to the stream are not initialized to any particular value. This is the same as the end-of-file behavior in the MS-DOS FAT file system. With a zero byte count and a seek pointer past the end of the stream, this method does not create the fill bytes to increase the stream to the seek pointer. In this case, you must call the IStream::SetSize method to increase the size of the stream and write the fill bytes. The pcbWritten parameter can have a value even if an error occurs. In the COM-provided implementation, stream objects are not sparse. Any fill bytes are eventually allocated on the disk and assigned to the stream. Read more on docs.microsoft.com. The IID guid for this interface. {0c733a30-2a1c-11ce-ade5-00aa0044773d} Acts as the factory method for any services exposed through an implementation of IServiceProvider. Accepts a CLSID parameter. The unique identifier of the service (an SID). The unique identifier of the interface that the caller wants to receive for the service. The address of the caller-allocated variable to receive the interface pointer of the service on successful return from this function. The caller becomes responsible for calling [Release](../unknwn/nf-unknwn-iunknown-release.md) through this interface pointer when the service is no longer required. S_OK on success. **QueryService** creates or accesses the implementation of the service identified with guidService. In ppv, it returns the address of the interface that is specified by riid. The IID guid for this interface. {6d5140c1-7436-11ce-8034-00aa006009fa} Changes the seek pointer to a new location. The new location is relative to either the beginning of the stream, the end of the stream, or the current seek pointer. The displacement to be added to the location indicated by the dwOrigin parameter. If dwOrigin is STREAM_SEEK_SET, this is interpreted as an unsigned value rather than a signed value. The origin for the displacement specified in dlibMove. The origin can be the beginning of the file (STREAM_SEEK_SET), the current seek pointer (STREAM_SEEK_CUR), or the end of the file (STREAM_SEEK_END). For more information about values, see the STREAM_SEEK enumeration. A pointer to the location where this method writes the value of the new seek pointer from the beginning of the stream. You can set this pointer to NULL. In this case, this method does not provide the new seek pointer. Read more on docs.microsoft.com. This method can return one of these values. | Return code | Description | |----------------|---------------| |S_OK | The seek pointer was successfully adjusted.| |E_PENDING | Asynchronous Storage only: Part or all of the stream data is currently unavailable. | |STG_E_INVALIDPOINTER | Indicates that *plibNewPosition* points to invalid memory, because *plibNewPosition* is not read.| |STG_E_INVALIDFUNCTION | The *dwOrigin* parameter contains an invalid value, or the *dlibMove* parameter contains a bad offset value. For example, the result of the seek pointer is a negative offset value.| |STG_E_REVERTED | The object has been invalidated by a revert operation above it in the transaction tree.| IStream::Seek changes the seek pointer so that subsequent read and write operations can be performed at a different location in the stream object. It is an error to seek before the beginning of the stream. It is not, however, an error to seek past the end of the stream. Seeking past the end of the stream is useful for subsequent write operations, as the stream byte range will be extended to the new seek position immediately before the write is complete. You can also use this method to obtain the current value of the seek pointer by calling this method with the dwOrigin parameter set to STREAM_SEEK_CUR and the dlibMove parameter set to 0 so that the seek pointer is not changed. The current seek pointer is returned in the plibNewPosition parameter. Read more on docs.microsoft.com. Changes the size of the stream object. Specifies the new size, in bytes, of the stream. This method can return one of these values. | Return code | Description | |----------------|---------------| |S_OK | The size of the stream object was successfully changed.| |E_PENDING | Asynchronous Storage only: Part or all of the stream's data is currently unavailable.| |STG_E_MEDIUMFULL | The stream size is not changed because there is no space left on the storage device.| |STG_E_INVALIDFUNCTION | The value of the *libNewSize* parameter is not supported by the implementation. Not all streams support greater than 232 bytes. If a stream does not support more than 232 bytes, the high DWORD data type of *libNewSize* must be zero. If it is nonzero, the implementation may return STG_E_INVALIDFUNCTION. In general, COM-based implementations of the IStream interface do not support streams larger than 232 bytes.| |STG_E_REVERTED | The object has been invalidated by a revert operation above it in the transaction tree.| IStream::SetSize changes the size of the stream object. Call this method to preallocate space for the stream. If the libNewSize parameter is larger than the current stream size, the stream is extended to the indicated size by filling the intervening space with bytes of undefined value. This operation is similar to the ISequentialStream::Write method if the seek pointer is past the current end of the stream. If the libNewSize parameter is smaller than the current stream, the stream is truncated to the indicated size. The seek pointer is not affected by the change in stream size. Calling IStream::SetSize can be an effective way to obtain a large chunk of contiguous space. Read more on docs.microsoft.com. Copies a specified number of bytes from the current seek pointer in the stream to the current seek pointer in another stream. A pointer to the destination stream. The stream pointed to by pstm can be a new stream or a clone of the source stream. The number of bytes to copy from the source stream. A pointer to the location where this method writes the actual number of bytes read from the source. You can set this pointer to NULL. In this case, this method does not provide the actual number of bytes read. A pointer to the location where this method writes the actual number of bytes written to the destination. You can set this pointer to NULL. In this case, this method does not provide the actual number of bytes written. This method can return one of these values. | Return code | Description | |----------------|---------------| |S_OK | The stream object was successfully copied.| |E_PENDING | Asynchronous Storage only: Part or all of the data to be copied is currently unavailable. | |STG_E_INVALIDPOINTER | The value of one of the pointer parameters is invalid.| |STG_E_MEDIUMFULL | The stream is not copied because there is no space left on the storage device.| |STG_E_REVERTED | The object has been invalidated by a revert operation above it in the transaction tree.| The CopyTo method copies the specified bytes from one stream to another. It can also be used to copy a stream to itself. The seek pointer in each stream instance is adjusted for the number of bytes read or written. This method is equivalent to reading cb bytes into memory using ISequentialStream::Read and then immediately writing them to the destination stream using ISequentialStream::Write, although IStream::CopyTo will be more efficient. The destination stream can be a clone of the source stream created by calling the IStream::Clone method. If IStream::CopyTo returns an error, you cannot assume that the seek pointers are valid for either the source or destination. Additionally, the values of pcbRead and pcbWritten are not meaningful even though they are returned. If IStream::CopyTo returns successfully, the actual number of bytes read and written are the same. To copy the remainder of the source from the current seek pointer, specify the maximum large integer value for the cb parameter. If the seek pointer is the beginning of the stream, this operation copies the entire stream. Read more on docs.microsoft.com. The Commit method ensures that any changes made to a stream object open in transacted mode are reflected in the parent storage. Controls how the changes for the stream object are committed. See the STGC enumeration for a definition of these values. Read more on docs.microsoft.com. This method can return one of these values. | Return code | Description | |----------------|---------------| |S_OK | Changes to the stream object were successfully committed to the parent level.| |E_PENDING | Asynchronous Storage only: Part or all of the stream's data is currently unavailable. | |STG_E_MEDIUMFULL | The commit operation failed due to lack of space on the storage device.| |STG_E_REVERTED | The object has been invalidated by a revert operation above it in the transaction tree.| The Commit method ensures that changes to a stream object opened in transacted mode are reflected in the parent storage. Changes that have been made to the stream since it was opened or last committed are reflected to the parent storage object. If the parent is opened in transacted mode, the parent may revert at a later time, rolling back the changes to this stream object. The compound file implementation does not support the opening of streams in transacted mode, so this method has very little effect other than to flush memory buffers. For more information, see IStream - Compound File Implementation. If the stream is open in direct mode, this method ensures that any memory buffers have been flushed out to the underlying storage object. This is much like a flush in traditional file systems. The IStream::Commit method is useful on a direct mode stream when the implementation of the IStream interface is a wrapper for underlying file system APIs. In this case, IStream::Commit would be connected to the file system's flush call. Read more on docs.microsoft.com. The Revert method discards all changes that have been made to a transacted stream since the last IStream::Commit call. On streams open in direct mode and streams using the COM compound file implementation of IStream::Revert, this method has no effect. This method can return one of these values. | Return code | Description | |----------------|---------------| |S_OK | The stream was successfully reverted to its previous version.| |E_PENDING | Asynchronous Storage only: Part or all of the stream's data is currently unavailable. | The Revert method discards changes made to a transacted stream since the last commit operation. The LockRegion method restricts access to a specified range of bytes in the stream. Integer that specifies the byte offset for the beginning of the range. Integer that specifies the length of the range, in bytes, to be restricted. Specifies the restrictions being requested on accessing the range. This method can return one of these values. | Return code | Description | |----------------|---------------| |S_OK | The specified range of bytes was locked.| |E_PENDING | Asynchronous Storage only: Part or all of the stream's data is currently unavailable. | |STG_E_INVALIDFUNCTION | Locking is not supported at all or the specific type of lock requested is not supported.| |STG_E_LOCKVIOLATION | Requested lock is supported, but cannot be granted because of an existing lock.| |STG_E_REVERTED | The object has been invalidated by a revert operation above it in the transaction tree.| The byte range of the stream can be extended. Locking an extended range for the stream is useful as a method of communication between different instances of the stream without changing data that is actually part of the stream. Three types of locking can be supported: locking to exclude other writers, locking to exclude other readers or writers, and locking that allows only one requester to obtain a lock on the given range, which is usually an alias for one of the other two lock types. A given stream instance might support either of the first two types, or both. The lock type is specified by dwLockType, using a value from the LOCKTYPE enumeration. Any region locked with IStream::LockRegion must later be explicitly unlocked by calling IStream::UnlockRegion with exactly the same values for the libOffset, cb, and dwLockType parameters. The region must be unlocked before the stream is released. Two adjacent regions cannot be locked separately and then unlocked with a single unlock call.

Notes to Callers

Since the type of locking supported is optional and can vary in different implementations of IStream, you must provide code to deal with the STG_E_INVALIDFUNCTION error. The LockRegion method has no effect in the compound file implementation, because the implementation does not support range locking.

Notes to Implementers

Support for this method is optional for implementations of stream objects since it may not be supported by the underlying file system. The type of locking supported is also optional. The STG_E_INVALIDFUNCTION error is returned if the requested type of locking is not supported. Read more on docs.microsoft.com. The UnlockRegion method removes the access restriction on a range of bytes previously restricted with IStream::LockRegion. Specifies the byte offset for the beginning of the range. Specifies, in bytes, the length of the range to be restricted. Specifies the access restrictions previously placed on the range. This method can return one of these values. | Return code | Description | |----------------|---------------| |S_OK | The byte range was unlocked.| |E_PENDING | Asynchronous Storage only: Part or all of the stream's data is currently unavailable.| |STG_E_INVALIDFUNCTION | Locking is not supported at all or the specific type of lock requested is not supported.| |STG_E_LOCKVIOLATION | The requested unlock operation cannot be granted.| |STG_E_REVERTED | The object has been invalidated by a revert operation above it in the transaction tree.| IStream::UnlockRegion unlocks a region previously locked with the IStream::LockRegion method. Locked regions must later be explicitly unlocked by calling IStream::UnlockRegion with exactly the same values for the libOffset, cb, and dwLockType parameters. The region must be unlocked before the stream is released. Two adjacent regions cannot be locked separately and then unlocked with a single unlock call. Read more on docs.microsoft.com. The Stat method retrieves the STATSTG structure for this stream. Pointer to a STATSTG structure where this method places information about this stream object. Read more on docs.microsoft.com. Specifies that this method does not return some of the members in the STATSTG structure, thus saving a memory allocation operation. Values are taken from the STATFLAG enumeration. Read more on docs.microsoft.com. This method can return one of these values. | Return code | Description | |----------------|---------------| |S_OK | The STATSTG structure was successfully returned at the specified location.| |E_PENDING | Asynchronous Storage only: Part or all of the stream's data is currently unavailable. | |STG_E_ACCESSDENIED | The caller does not have enough permissions for accessing statistics for this storage object.| |STG_E_INSUFFICIENTMEMORY | The STATSTG structure was not returned due to a lack of memory.| |STG_E_INVALIDFLAG | The value for the *grfStateFlag* parameter is not valid.| |STG_E_INVALIDPOINTER | The *pStatStg* pointer is not valid.| |STG_E_REVERTED | The object has been invalidated by a revert operation above it in the transaction tree.| IStream::Stat retrieves a pointer to the STATSTG structure that contains information about this open stream. When this stream is within a structured storage and IStorage::EnumElements is called, it creates an enumerator object with the IEnumSTATSTG interface on it, which can be called to enumerate the storages and streams through the STATSTG structures associated with each of them. Read more on docs.microsoft.com. The Clone method creates a new stream object with its own seek pointer that references the same bytes as the original stream. When successful, pointer to the location of an IStream pointer to the new stream object. If an error occurs, this parameter is NULL. Read more on docs.microsoft.com. This method can return one of these values. | Return code | Description | |----------------|---------------| |S_OK | The stream was successfully cloned.| |E_PENDING | Asynchronous Storage only: Part or all of the stream's data is currently unavailable. | |STG_E_INSUFFICIENTMEMORY | The stream was not cloned due to a lack of memory.| |STG_E_INVALIDPOINTER | The ppStm pointer is not valid.| |STG_E_REVERTED | The object has been invalidated by a revert operation above it in the transaction tree.| The Clone method creates a new stream object for accessing the same bytes but using a separate seek pointer. The new stream object sees the same data as the source-stream object. Changes written to one object are immediately visible in the other. Range locking is shared between the stream objects. The initial setting of the seek pointer in the cloned stream instance is the same as the current setting of the seek pointer in the original stream at the time of the clone operation. Read more on docs.microsoft.com. The IID guid for this interface. {0000000c-0000-0000-c000-000000000046} Maps a name to a member of a type, or binds global variables and functions contained in a type library. The name to be bound. The hash value for the name computed by LHashValOfNameSys. One or more of the flags defined in the INVOKEKIND enumeration. Specifies whether the name was referenced as a method or a property. When binding to a variable, specify the flag INVOKE_PROPERTYGET. Specify zero to bind to any type of member. If a FUNCDESC or VARDESC was returned, then ppTInfo points to a pointer to the type description that contains the item to which it is bound. Indicates whether the name bound to is a VARDESC, FUNCDESC, or TYPECOMP. If there was no match, DESCKIND_NONE. The bound-to VARDESC, FUNCDESC, or ITypeComp interface. This method can return one of these values. This doc was truncated. Use Bind for binding to the variables and methods of a type, or for binding to the global variables and methods in a type library. The returned DESCKIND pointer pDescKind indicates whether the name was bound to a VARDESC, a FUNCDESC, or to an ITypeComp instance. The returned pBindPtr points to the VARDESC, FUNCDESC, or ITypeComp. If a data member or method is bound to, then ppTInfopoints to the type description that contains the method or data member. If Bind binds the name to a nested binding context, it returns a pointer to an ITypeComp instance in pBindPtr and a null type description pointer in ppTInfo. For example, if the name of a type description is passed for a module (TKIND_MODULE), enumeration (TKIND_ENUM), or coclass (TKIND_COCLASS), Bind returns the ITypeComp instance of the type description for the module, enumeration, or coclass. This feature supports languages such as Visual Basic that allow references to members of a type description to be qualified by the name of the type description. For example, a function in a module can be referenced by modulename.functionname. The members of TKIND_ENUM, TKIND_MODULE, and TKIND_COCLASS types marked as Application objects can be bound to directly from ITypeComp, without specifying the name of the module. The ITypeComp of a coclass defers to the ITypeComp of its default interface. As with other methods of ITypeComp, ITypeInfo, and ITypeInfo, the calling code is responsible for releasing the returned object instances or structures. If a VARDESC or FUNCDESC is returned, the caller is responsible for deleting it with the returned type description and releasing the type description instance itself. Otherwise, if an ITypeComp instance is returned, the caller must release it. Special rules apply if you call a type library's Bind method, passing it the name of a member of an Application object class (a class that has the TYPEFLAG_FAPPOBJECT flag set). In this case, Bind returns DESCKIND_IMPLICITAPPOBJ in pDescKind, a VARDESC that describes the Application object in pBindPtr, and the ITypeInfo of the Application object class in ppTInfo. To bind to the object, ITypeInfo::GetTypeComp must make a call to get the ITypeComp of the Application object class, and then reinvoke its Bind method with the name initially passed to the type library's ITypeComp. The caller should use the returned ITypeInfo pointer (ppTInfo) to get the address of the member.
Note  The wflags parameter is the same as the wflags parameter in IDispatch::Invoke.
 
 Read more on docs.microsoft.com. Binds to the type descriptions contained within a type library. The name to be bound. The hash value for the name computed by LHashValOfName. An ITypeInfo of the type to which the name was bound. Passes a valid pointer, such as the address of an ITypeComp variable. This method can return one of these values. This doc was truncated. Use the function BindType for binding a type name to the ITypeInfo that describes the type. This function is invoked on the ITypeComp that is returned by ITypeLib::GetTypeComp to bind to types defined within that library. It can also be used in the future for binding to nested types. The IID guid for this interface. {00020403-0000-0000-c000-000000000046} Provides the number of type descriptions that are in a type library. The number of type descriptions in the type library. Learn more about this API from docs.microsoft.com. Retrieves the specified type description in the library. The index of the interface to be returned. If successful, returns a pointer to the pointer to the ITypeInfo interface. This method can return one of these values. This doc was truncated. For dual interfaces, GetTypeInfo returns only the TKIND_DISPATCH type information. To get the TKIND_INTERFACE type information, GetRefTypeOfImplType can be called on the TKIND_DISPATCH type information, passing an index of –1. Then, the returned type information handle can be passed to GetRefTypeInfo. Retrieves the type of a type description. The index of the type description within the type library. The TYPEKIND enumeration value for the type description. This method can return one of these values. This doc was truncated. Learn more about this API from docs.microsoft.com. Retrieves the type description that corresponds to the specified GUID. The GUID of the type description. The ITypeInfo interface. This method can return one of these values. This doc was truncated. Learn more about this API from docs.microsoft.com. Retrieves the structure that contains the library's attributes. The library's attributes. This method can return one of these values. This doc was truncated. Use ITypeLib::ReleaseTLibAttr to free the memory occupied by the TLIBATTR structure. Enables a client compiler to bind to the types, variables, constants, and global functions for a library. The ITypeComp instance for this ITypeLib. A client compiler uses the methods in the ITypeComp interface to bind to types in ITypeLib, as well as to the global functions, variables, and constants defined in ITypeLib This method can return one of these values. This doc was truncated. The Bind function of the returned TypeComp binds to global functions, variables, constants, enumerated values, and coclass members. The Bind function also binds the names of the TYPEKIND enumerations of TKIND_MODULE, TKIND_ENUM, and TKIND_COCLASS. These names shadow any global names defined within the type information. The members of TKIND_ENUM, TKIND_MODULE, and TKIND_COCLASS types marked as Application objects can be directly bound to from ITypeComp without specifying the name of the module. ITypeComp::Bind and ITypeComp::BindType accept only unqualified names. ITypeLib::GetTypeComp returns a pointer to the ITypeComp interface, which is then used to bind to global elements in the library. The names of some types (TKIND_ENUM, TKIND_MODULE, and TKIND_COCLASS) share the name space with variables, functions, constants, and enumerators. If a member requires qualification to differentiate it from other items in the name space, GetTypeComp can be called successively for each qualifier in order to bind to the desired member. This allows programming language compilers to access members of modules, enumerations, and coclasses, even though the member can't be bound to with a qualified name. Read more on docs.microsoft.com. Retrieves the documentation string for the library, the complete Help file name and path, and the context identifier for the library Help topic in the Help file. The index of the type description whose documentation is to be returned. If index is -1, then the documentation for the library itself is returned. The name of the specified item. If the caller does not need the item name, then pBstrName can be null. The documentation string for the specified item. If the caller does not need the documentation string, then pBstrDocString can be null.. The Help context identifier (ID) associated with the specified item. If the caller does not need the Help context ID, then pdwHelpContext can be null. The fully qualified name of the Help file. If the caller does not need the Help file name, then pBstrHelpFile can be null. This method can return one of these values. This doc was truncated. The caller should free the parameters pBstrName, pBstrDocString, and pBstrHelpFile. Indicates whether a passed-in string contains the name of a type or member described in the library. The string to test. If this method is successful, szNameBuf is modified to match the case (capitalization) found in the type library. The hash value of szNameBuf. True if szNameBuf was found in the type library; otherwise false. This method can return one of these values. This doc was truncated. Learn more about this API from docs.microsoft.com. Finds occurrences of a type description in a type library. This may be used to quickly verify that a name exists in a type library. The name to search for. A hash value to speed up the search, computed by the LHashValOfNameSys function. If lHashVal = 0, a value is computed. An array of pointers to the type descriptions that contain the name specified in szNameBuf. This parameter cannot be null. An array of the found items; rgMemId[i] is the MEMBERID that indexes into the type description specified by ppTInfo[i]. This parameter cannot be null. On entry, indicates how many instances to look for. For example, *pcFound = 1 can be called to find the first occurrence. The search stops when one is found. On exit, indicates the number of instances that were found. If the in and out values of *pcFound are identical, there may be more type descriptions that contain the name. Read more on docs.microsoft.com. This method can return one of these values. This doc was truncated. Passing *pcFound = n indicates that there is enough room in the ppTInfo and rgMemId arrays for n (ptinfo, memid) pairs. The function returns MEMBERID_NIL in rgMemId[i], if the name in szNameBuf is the name of the type information in ppTInfo[i]. Releases the TLIBATTR originally obtained from GetLibAttr. The TLIBATTR to be freed. Learn more about this API from docs.microsoft.com. The IID guid for this interface. {00020402-0000-0000-c000-000000000046} The LOCKTYPE enumeration values indicate the type of locking requested for the specified range of bytes. The values are used in the ILockBytes::LockRegion and IStream::LockRegion methods. Learn more about this API from docs.microsoft.com. If this lock is granted, the specified range of bytes can be opened and read any number of times, but writing to the locked range is prohibited except for the owner that was granted this lock. If this lock is granted, writing to the specified range of bytes is prohibited except by the owner that was granted this lock. If this lock is granted, no other LOCK_ONLYONCE lock can be obtained on the range. Usually this lock type is an alias for some other lock type. Thus, specific implementations can have additional behavior associated with this lock type. Represents the bounds of one dimension of the array. Learn more about this API from docs.microsoft.com. The number of elements in the dimension. The lower bound of the dimension. Contains information used to specify each advisory connection. Learn more about this API from docs.microsoft.com. The FORMATETC structure for the data of interest to the advise sink. The advise sink receives notification of changes to the data specified by this FORMATETC structure. The ADVF enumeration value that determines when the advisory sink is notified of changes in the data. The pointer for the IAdviseSink interface that will receive change notifications. The token that uniquely identifies the advisory connection. This token is returned by the method that sets up the advisory connection. Indicate whether the method should try to return a name in the pwcsName member of the STATSTG structure. Learn more about this API from docs.microsoft.com. Requests that the statistics include the pwcsName member of the STATSTG structure. Read more on docs.microsoft.com. Requests that the statistics not include the pwcsName member of the STATSTG structure. If the name is omitted, there is no need for the ILockBytes::Stat, IStorage::Stat, and IStream::Stat methods methods to allocate and free memory for the string value of the name, therefore the method reduces time and resources used in an allocation and free operation. Read more on docs.microsoft.com. Not implemented. Contains statistical data about an open storage, stream, or byte-array object. Learn more about this API from docs.microsoft.com. A pointer to a NULL-terminated Unicode string that contains the name. Space for this string is allocated by the method called and freed by the caller (for more information, see CoTaskMemFree). To not return this member, specify the STATFLAG_NONAME value when you call a method that returns a STATSTG structure, except for calls to IEnumSTATSTG::Next, which provides no way to specify this value. Read more on docs.microsoft.com. Indicates the type of storage object. This is one of the values from the STGTY enumeration. Read more on docs.microsoft.com. Specifies the size, in bytes, of the stream or byte array. Indicates the last modification time for this storage, stream, or byte array. Indicates the creation time for this storage, stream, or byte array. Indicates the last access time for this storage, stream, or byte array. Indicates the access mode specified when the object was opened. This member is only valid in calls to Stat methods. Read more on docs.microsoft.com. Indicates the class identifier for the storage object; set to CLSID_NULL for new storage objects. This member is not used for streams or byte arrays. Indicates the current state bits of the storage object; that is, the value most recently set by the IStorage::SetStateBits method. This member is not valid for streams or byte arrays. Read more on docs.microsoft.com. Reserved for future use. Flags that indicate conditions for creating and deleting the object and access modes for the object. You can combine these flags, but you can only choose one flag from each group of related flags. Typically one flag from each of the access and sharing groups must be specified for all functions and methods which use these constants. Flags from other groups are optional. The STGTY enumeration values are used in the type member of the STATSTG structure to indicate the type of the storage element. A storage element is a storage object, a stream object, or a byte-array object (LOCKBYTES). Learn more about this API from docs.microsoft.com. Indicates that the storage element is a storage object. Indicates that the storage element is a stream object. Indicates that the storage element is a byte-array object. Indicates that the storage element is a property storage object. Identifies the target operating system platform. Learn more about this API from docs.microsoft.com. The target operating system for the type library is 16-bit Windows. By default, data members are packed. The target operating system for the type library is 32-bit Windows. By default, data members are naturally aligned (for example, 2-byte integers are aligned on even-byte boundaries; 4-byte integers are aligned on quad-word boundaries, and so on). The target operating system for the type library is Apple Macintosh. By default, all data members are aligned on even-byte boundaries. The target operating system for the type library is 64-bit Windows. Contains information about a type library. Information from this structure is used to identify the type library and to provide national language support for member names. Learn more about this API from docs.microsoft.com. The globally unique identifier. The locale identifier. The target hardware platform. The major version number. The minor version number. The library flags. Indicates the type of storage medium being used in a data transfer. They are used in the STGMEDIUM or FORMATETC structures. During data transfer operations, a storage medium is specified. This medium must be released after the data transfer operation. The provider of the medium indicates its choice of ownership scenarios in the value it provides in the STGMEDIUM structure. A NULL value for the pUnkForRelease member indicates that the receiving body of code owns and can free the medium. A non-NULL pointer specifies that ReleaseStgMedium can always be called to free the medium. The storage medium is a global memory handle (HGLOBAL). Allocate the global handle with the GMEM_MOVEABLE flag. If the punkForRelease member of STGMEDIUM is NULL, the destination process should use GlobalFree to release the memory. The storage medium is a disk file identified by a path. If the STGMEDIUM punkForRelease member is NULL, the destination process should use OpenFile to delete the file. The storage medium is a stream object identified by an IStream pointer. Use ISequentialStream::Read to read the data. If the STGMEDIUM punkForRelease member is not NULL, the destination process should use Release to release the stream component. The storage medium is a storage component identified by an IStorage pointer. The data is in the streams and storages contained by this IStorage instance. If the STGMEDIUM punkForRelease member is not NULL, the destination process should use Release to release the storage component. The storage medium is a GDI component (HBITMAP). If the STGMEDIUM punkForRelease member is NULL, the destination process should use DeleteObject to delete the bitmap. The storage medium is a metafile (METAFILEPICT). Use the GDI functions to access the metafile's data. If the STGMEDIUM punkForRelease member is NULL, the destination process should use DeleteMetaFile to delete the bitmap. The storage medium is an enhanced metafile (HENHMETAFILE). If the STGMEDIUM punkForRelease member is NULL, the destination process should use DeleteEnhMetaFile to delete the bitmap. No data is being passed. Contains attributes of a type. Learn more about this API from docs.microsoft.com. The GUID of the type information. The locale of member names and documentation strings. Reserved. The constructor ID, or MEMBERID_NIL if none. The destructor ID, or MEMBERID_NIL if none. Reserved. The size of an instance of this type. The kind of type. The number of functions. The number of variables or data members. The number of implemented interfaces. The size of this type's VTBL. The byte alignment for an instance of this type. A value of 0 indicates alignment on the 64K boundary; 1 indicates no special alignment. For other values, n indicates aligned on byte n. The type flags. See TYPEFLAGS. The major version number. The minor version number. If typekind is TKIND_ALIAS, specifies the type for which this type is an alias. The IDL attributes of the described type. Describes the type of a variable, the return type of a function, or the type of a function parameter. If the variable is VT_SAFEARRAY or VT_PTR, the union portion of the TYPEDESC contains a pointer to a TYPEDESC that specifies the element type. The variant type. Specifies a type. Learn more about this API from docs.microsoft.com. A set of enumerators. A structure with no methods. A module that can only have static functions and data (for example, a DLL). A type that has virtual and pure functions. A set of methods and properties that are accessible through IDispatch::Invoke. By default, dual interfaces return TKIND_DISPATCH. A set of implemented component object interfaces. A type that is an alias for another type. A union, all of whose members have an offset of zero. End of enum marker. Describes a variable, constant, or data member. Learn more about this API from docs.microsoft.com. The member ID. Reserved. The variable type. The variable flags. See VARFLAGS. The variable type. Specifies variable flags. Learn more about this API from docs.microsoft.com. Assignment to the variable should not be allowed. The variable returns an object that is a source of events. The variable supports data binding. When set, any attempt to directly change the property results in a call to IPropertyNotifySink::OnRequestEdit. The implementation of OnRequestEdit determines if the change is accepted. The variable is displayed to the user as bindable. VARFLAG_FBINDABLE must also be set. The variable is the single property that best represents the object. Only one variable in type information can have this attribute. The variable should not be displayed to the user in a browser, although it exists and is bindable. The variable should not be accessible from macro languages. This flag is intended for system-level variables or variables that you do not want type browsers to display. Permits an optimization in which the compiler looks for a member named "xyz" on the type of abc. If such a member is found and is flagged as an accessor function for an element of the default collection, then a call is generated to that member function. Permitted on members in dispinterfaces and interfaces; not permitted on modules. The variable is the default display in the user interface. The variable appears in an object browser, but not in a properties browser. Tags the interface as having default behaviors. The variable is mapped as individual bindable properties. Specifies the variable type. Learn more about this API from docs.microsoft.com. The variable is a field or member of the type. It exists at a fixed offset within each instance of the type. There is only one instance of the variable. The VARDESC describes a symbolic constant. There is no memory associated with it. The variable can only be accessed through IDispatch::Invoke. Describes an array, its element type, and its dimension. Learn more about this API from docs.microsoft.com. The element type. The dimension count. A variable-length array containing one element for each dimension. Computes the amount of memory that must be allocated to store this struct, including the specified number of elements in the variable length inline array at the end. Represents information about the effects of a drag-and-drop operation. 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: This doc was truncated. Read more on docs.microsoft.com. The IID guid for this interface. {a6ef9860-c720-11d0-9337-00a0c90dcaa9} 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. This doc was truncated. 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. 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. This doc was truncated. 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. Read more on docs.microsoft.com. The IID guid for this interface. {00000121-0000-0000-c000-000000000046} 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. Learn more about this API from docs.microsoft.com. 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. Learn more about this API from docs.microsoft.com. The IID guid for this interface. {0000012b-0000-0000-c000-000000000046} 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. This doc was truncated. 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: This doc was truncated. Read more on docs.microsoft.com. 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. This doc was truncated. 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. This doc was truncated. Read more on docs.microsoft.com. Removes target feedback and releases the data object. This method returns S_OK on success. Other possible values include the following. This doc was truncated. You do not call this method directly. The DoDragDrop function calls this method in either of the following cases: This doc was truncated. Read more on docs.microsoft.com. 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. This doc was truncated. 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: This doc was truncated. Read more on docs.microsoft.com. The IID guid for this interface. {00000122-0000-0000-c000-000000000046} Retrieves the handle to the picture managed within this picture object to a specified location. A pointer to a variable that receives the handle. The caller is responsible for this handle upon successful return. The variable is set to NULL on failure. This method supports the standard return values E_FAIL and E_OUTOFMEMORY, as well as the following values. This doc was truncated.

Notes to Callers

The picture object may retain ownership of the picture. However, the caller can be assured that the picture will remain valid until either the caller specifically destroys the picture or the picture object is itself destroyed. The fOwn parameter to OleCreatePictureIndirect determines ownership when the picture object is created. OleLoadPicture forces fOwn to TRUE. Read more on docs.microsoft.com. Retrieves a copy of the palette currently used by the picture object. A pointer to a variable that receives the palette handle. The variable is set to NULL on failure. This method supports the standard return values E_FAIL and E_OUTOFMEMORY, as well as the following values. This doc was truncated.

Notes to Callers

If the picture object has ownership of the picture, it also has ownership of the palette and will destroy it when the object is itself destroyed. Otherwise the caller owns the palette. The fOwn parameter to OleCreatePictureIndirect determines ownership. OleLoadPicture sets fOwn to TRUE to indicate that the picture object owns the palette. Read more on docs.microsoft.com. Retrieves the current type of the picture contained in the picture object. Pointer to a variable that receives the picture type. The Type property can have any one of the values contained in the PICTYPE enumeration. This method supports the standard return value E_FAIL, as well as the following values. This doc was truncated. Learn more about this API from docs.microsoft.com. Retrieves the current width of the picture in the picture object. A pointer to a variable that receives the width. This method supports the standard return value E_FAIL, as well as the following values. This doc was truncated. Learn more about this API from docs.microsoft.com. Retrieves the current height of the picture in the picture object. A pointer to a variable that receives the height. This method supports the standard return value E_FAIL, as well as the following values. This doc was truncated. Learn more about this API from docs.microsoft.com. Renders (draws) a specified portion of the picture defined by the offset (xSrc,ySrc) of the source picture and the dimensions to copy (cxSrc,xySrc). A handle of the device context on which to render the image. The horizontal coordinate in hdc at which to place the rendered image. The vertical coordinate in hdc at which to place the rendered image. The horizontal dimension (width) of the destination rectangle. The vertical dimension (height) of the destination rectangle The horizontal offset in the source picture from which to start copying. The vertical offset in the source picture from which to start copying. The horizontal extent to copy from the source picture. The vertical extent to copy from the source picture. A pointer to a rectangle containing the position of the destination within a metafile device context if hdc is a metafile DC. Cannot be NULL in such cases. This method supports the standard return values E_FAIL, E_INVALIDARG, and E_OUTOFMEMORY, as well as the following: This doc was truncated. Learn more about this API from docs.microsoft.com. Assigns a GDI palette to the picture contained in the picture object. A handle to the GDI palette assigned to the picture. This method supports the standard return values E_FAIL, E_INVALIDARG, E_OUTOFMEMORY, and S_OK.

Notes to Implementers

Ownership of the palette passed to this method depends on how the picture object was created, as specified by the fOwn parameter to OleCreatePictureIndirect. OleLoadPicture forces fOwn to TRUE; if the object owns the picture, then it takes over ownership of this palette. Read more on docs.microsoft.com. Retrieves the handle of the current device context. This property is valid only for bitmap pictures. A pointer a variable that receives the device context. This method supports the standard return value E_FAIL, as well as the following values. This doc was truncated. The CurDC property and the IPicture::SelectPicture method exist to circumvent restrictions in Windows; specifically, that an object can only be selected into exactly one device context at a time. In some cases, a picture object may be permanently selected into a particular device context (for example, a control may use a certain picture for a background). To use this picture property elsewhere, it must be temporarily deselected from its old device context, selected into the new device context for the operation, then reselected back into the old device context. The IPicture::get_CurDC method returns the device context handle into which the picture is currently selected. The IPicture::SelectPicture method selects the picture into a new device context, returning the old device context and the picture's GDI handle. The caller should select the picture back into the old device context when the caller is done with it, as is normal for Windows code.

Notes to Callers

The caller always owns any device contexts passed between it and the picture object. Because the picture object maintains a copy of the HDC, the caller should use a memory device context (created with the CreateCompatibleDC function) and not a screen device context (from GetDC, CreateDC, or BeginPaint), because the screen device contexts are a limited system resource. Read more on docs.microsoft.com. Selects a bitmap picture into a given device context, and returns the device context in which the picture was previously selected as well as the picture's GDI handle. This method works in conjunction with IPicture::get_CurDC. A handle for the device context in which to select the picture. A pointer to a variable that receives the previous device context. This parameter can be NULL if the caller does not need this information. Ownership of the device context is always the responsibility of the caller. A pointer to a variable that receives the GDI handle of the picture. This parameter can be NULL if the caller does not need the handle. Ownership of this handle is determined by the fOwn parameter passed to OleCreatePictureIndirect. Pictures loaded from a stream always own their resources. This method supports the standard return values E_FAIL, E_INVALIDARG, E_OUTOFMEMORY, and S_OK. Learn more about this API from docs.microsoft.com. Retrieves the current value of the picture's KeepOriginalFormat property. A pointer to a variable that receives the value of the property. This method supports the standard return value E_FAIL, as well as the following value. This doc was truncated. Learn more about this API from docs.microsoft.com. Sets the value of the picture's KeepOriginalFormat property. Specifies the new value to assign to the property. This method returns S_OK on success and E_FAIL otherwise. Learn more about this API from docs.microsoft.com. Notifies the picture object that its picture resource has changed. This method only calls IPropertyNotifySink::OnChanged with DISPID_PICT_HANDLE for any connected sinks. This method S_OK if it succeeds and E_FAIL if the picture object is uninitialized. Learn more about this API from docs.microsoft.com. Saves the picture's data into a stream in the same format that it would save itself into a file. Bitmaps use the BMP file format, metafiles the WMF format, and icons the ICO format. A pointer to the stream into which the picture writes its data. A flag indicating whether to save a copy of the picture in memory. Pointer to a variable that receives the number of bytes written into the stream. This value can be NULL, indicating that the caller does not require this information. This method supports the standard return values E_FAIL, E_INVALIDARG, and S_OK. Learn more about this API from docs.microsoft.com. Retrieves the current set of the picture's bit attributes. A pointer to a variable that receives the value of the Attributes property. The Attributes property can contain any combination of the values from the PICTUREATTRIBUTES enumeration. Read more on docs.microsoft.com. This method supports the standard return value E_FAIL, as well as the following values. This doc was truncated. Learn more about this API from docs.microsoft.com. The IID guid for this interface. {7bf80980-bf32-101a-8bbb-00aa00300cab} The IID guid for this interface. {7bf80981-bf32-101a-8bbb-00aa00300cab} Initializes a new instance of a record. An instance of a record. This method can return one of these values. This doc was truncated. The caller must allocate the memory of the record by its appropriate size using the GetSize method. RecordInit sets all contents of the record to 0 and the record should hold no resources. Read more on docs.microsoft.com. Releases object references and other values of a record without deallocating the record. The record to be cleared. This method can return one of these values. This doc was truncated. RecordClear releases memory blocks held by VT_PTR or VT_SAFEARRAY instance fields. The caller needs to free the instance fields memory, RecordClear will do nothing if there are no resources held. Copies an existing record into the passed in buffer. The current record instance. The destination where the record will be copied. This method can return one of these values. This doc was truncated. RecordCopy will release the resources in the destination first. The caller is responsible for allocating sufficient memory in the destination by calling GetSize or RecordCreate. If RecordCopy fails to copy any of the fields then all fields will be cleared, as though RecordClear had been called. Gets the GUID of the record type. The class GUID of the TypeInfo that describes the UDT. This method can return one of these values. This doc was truncated. Learn more about this API from docs.microsoft.com. Gets the name of the record type. The name. This method can return one of these values. This doc was truncated. The caller must free the BSTR by calling SysFreeString. Gets the number of bytes of memory necessary to hold the record instance. The size of a record instance, in bytes. This method can return one of these values. This doc was truncated. Learn more about this API from docs.microsoft.com. Retrieves the type information that describes a UDT or safearray of UDTs. The information type of the record. This method can return one of these values. This doc was truncated. AddRef is called on the pointer ppTypeInfo. Returns a pointer to the VARIANT containing the value of a given field name. The instance of a record. The field name. The VARIANT that you want to hold the value of the field name, szFieldName. On return, places a copy of the field's value in the variant. This method can return one of these values. This doc was truncated. The VARIANT that you pass in contains a copy of the field's value upon return. If you modify the VARIANT then the underlying record field does not change. The caller allocates memory of the VARIANT. The method VariantClear is called for pvarField before copying. Read more on docs.microsoft.com. Returns a pointer to the value of a given field name without copying the value and allocating resources. The instance of a record. The name of the field. The VARIANT that will contain the UDT upon return. Receives the value of the field upon return. This method can return one of these values. This doc was truncated. Upon return, the VARIANT you pass contains a direct pointer to the record's field, ppvDataCArray. If you modify the VARIANT, then the underlying record field will change. The caller allocates memory of the VARIANT, but does not own the memory so cannot free pvarField. This method calls VariantClear for pvarField before filling in the requested field. Read more on docs.microsoft.com. Puts a variant into a field. The only legal values for the wFlags parameter is INVOKE_PROPERTYPUT or INVOKE_PROPERTYPUTREF. If INVOKE_PROPERTYPUTREF is passed in then PutField just assigns the value of the variant that is passed in to the field using normal coercion rules. If INVOKE_PROPERTYPUT is passed in then specific rules apply. If the field is declared as a class that derives from IDispatch and the field's value is NULL then an error will be returned. If the field's value is not NULL then the variant will be passed to the default property supported by the object referenced by the field. If the field is not declared as a class derived from IDispatch then an error will be returned. If the field is declared as a variant of type VT_Dispatch then the default value of the object is assigned to the field. Otherwise, the variant's value is assigned to the field. Read more on docs.microsoft.com. The pointer to an instance of the record. The name of the field of the record. The pointer to the variant. This method can return one of these values. This doc was truncated. Learn more about this API from docs.microsoft.com. Passes ownership of the data to the assigned field by placing the actual data into the field. The only legal values for the wFlags parameter is INVOKE_PROPERTYPUT or INVOKE_PROPERTYPUTREF. An instance of the record described by IRecordInfo. The name of the field of the record. The variant to be put into the field. This method can return one of these values. This doc was truncated. Learn more about this API from docs.microsoft.com. Gets the names of the fields of the record. The number of names to return. The name of the array of type BSTR. If the rgBstrNames parameter is NULL, then pcNames is returned with the number of field names. It the rgBstrNames parameter is not NULL, then the string names contained in rgBstrNames are returned. If the number of names in pcNames and rgBstrNames are not equal then the lesser number of the two is the number of returned field names. The caller needs to free the BSTRs inside the array returned in rgBstrNames. Read more on docs.microsoft.com. This method can return one of these values. This doc was truncated. The caller should allocate memory for the array of BSTRs. If the array is larger than needed, set the unused portion to 0. On return, the caller will need to free each contained BSTR using SysFreeString. In case of out of memory, pcNames points to error code. Read more on docs.microsoft.com. Determines whether the record that is passed in matches that of the current record information. The information of the record. This doc was truncated. Learn more about this API from docs.microsoft.com. Allocates memory for a new record, initializes the instance and returns a pointer to the record. This method returns a pointer to the created record. The memory is set to zeros before it is returned. The records created must be freed by calling RecordDestroy. Read more on docs.microsoft.com. Creates a copy of an instance of a record to the specified location. An instance of the record to be copied. The new record with data copied from pvSource. This method can return one of these values. This doc was truncated. The records created must be freed by calling RecordDestroy. Releases the resources and deallocates the memory of the record. An instance of the record to be destroyed. This method can return one of these values. This doc was truncated. RecordClear is called to release the resources held by the instance of a record without deallocating memory.
Note  This method can only be called on records allocated through RecordCreate and RecordCreateCopy. If you allocate the record yourself, you cannot call this method.
 
 Read more on docs.microsoft.com. The IID guid for this interface. {0000002f-0000-0000-c000-000000000046} Contains information needed for transferring a structure element, parameter, or function return value between processes. Learn more about this API from docs.microsoft.com. The default value for the parameter, if PARAMFLAG_FHASDEFAULT is specified in wParamFlags. The parameter flags. See PARAMFLAG Constants. Contains information about the default value of a parameter. Learn more about this API from docs.microsoft.com. The size of the structure. The default value of the parameter. Contains parameters to create a picture object through the OleCreatePictureIndirect function. Learn more about this API from docs.microsoft.com. The size of the structure, in bytes. Describe the type of a picture object as returned by IPicture get\_Type, as well as to describe the type of picture in the picType member of the PICTDESC structure that is passed to OleCreatePictureIndirect. Learn more about this API from docs.microsoft.com. VARIANTARG describes arguments passed within DISPPARAMS, and VARIANT to specify variant data that cannot be passed by reference. Learn more about this API from docs.microsoft.com. Converts the given object to . Specifies the variant types. The following table shows where these values can be used. This doc was truncated. Read more on docs.microsoft.com. Not specified. Null. A 2-byte integer. A 4-byte integer. A 4-byte real. An 8-byte real. Currency. A date. A string. An IDispatch pointer. An SCODE value. A Boolean value. True is -1 and false is 0. A variant pointer. An IUnknown pointer. A 16-byte fixed-pointer value. A character. An unsigned character. An unsigned short. An unsigned long. A 64-bit integer. A 64-bit unsigned integer. An integer. An unsigned integer. A C-style void. An HRESULT value. A pointer type. A safe array. Use VT_ARRAY in VARIANT. A C-style array. A user-defined type. A null-terminated string. A wide null-terminated string. A user-defined type. A signed machine register size width. An unsigned machine register size width. A FILETIME value. Length-prefixed bytes. The name of the stream follows. The name of the storage follows. The stream contains an object. The storage contains an object. The blob contains an object. A clipboard format. A class ID. A stream with a GUID version. Reserved. A simple counted array. A SAFEARRAY pointer. A void pointer for local use. The data type RPC\_STATUS represents a platform-specific status code type. The **RPC\_STATUS** type is returned by most RPC functions and is part of the [**RPC\_OBJECT\_INQ\_FN**](/windows/desktop/api/Rpcdce/nc-rpcdce-rpc_object_inq_fn) function type definition. Returns if built-in COM interop is supported. When using AOT or trimming this will return . Gets a pointer for the specified for the given . Throws if the desired pointer can not be obtained. Attempts to get a pointer for the specified for the given . Attempts to get a pointer for the specified for the given . Gets the specified interface for the given . Throws if the desired pointer can not be obtained. Attempts to get the specified interface for the given . The requested pointer or if unsuccessful. Queries for the given interface and releases it. Note that this method should only be used for the purposes of checking if the object supports a given interface. If that interface is needed, it is best try to get the ComScope directly to avoid querying twice. Attempts to get the specified interface for the given . Typically either or . Check for success, not specific results. The requested pointer or if unsuccessful. Attempts to unwrap a ComWrapper CCW as a particular managed object. Attempts to get a managed wrapper of the specified type for the given COM interface. When , releases the original whether successful or not. Returns if the given is projected as the given . capable wrapper for . is . Find the given interface's from the specified type library. vtable population hook for CsWin32's generated implementation. Contains strings that identify the driver, device, and output port names for a printer. Learn more about this API from https://learn.microsoft.com. Manually copied from a 64 bit project CsWin32 generated wrapper. We can't directly use CsWin32 for this as it technically isn't compatible with AnyCPU. For our usages this works fine on both 32 bit and 64 bit. This is defined with single byte packing on 32 bit, but there are no gaps as everything naturally packs with no gaps on 32 bit. Issues would arise if this was contained in another native struct where it wouldn't start 32 bit aligned due to the single byte packing. https://github.com/microsoft/CsWin32/issues/882 Type: WORD The offset, in characters, from the beginning of this structure to a null-terminated string that contains the file name (without the extension) of the device driver. On input, this string is used to determine the printer to display initially in the dialog box. Read more on https://learn.microsoft.com. Type: WORD The offset, in characters, from the beginning of this structure to the null-terminated string that contains the name of the device. Read more on https://learn.microsoft.com. Type: WORD The offset, in characters, from the beginning of this structure to the null-terminated string that contains the device name for the physical output medium (output port). Read more on https://learn.microsoft.com. Type: WORD Indicates whether the strings contained in the DEVNAMES structure identify the default printer. This string is used to verify that the default printer has not changed since the last print operation. If any of the strings do not match, a warning message is displayed informing the user that the document may need to be reformatted. On output, the wDefault member is changed only if the Print Setup dialog box was displayed and the user chose the OK button. The DN_DEFAULTPRN flag is used if the default printer was selected. If a specific printer is selected, the flag is not used. All other flags in this member are reserved for internal use by the dialog box procedure for the Print property sheet or Print dialog box. Read more on https://learn.microsoft.com. Contains information that the PrintDlgEx function uses to initialize the Print property sheet. After the user closes the property sheet, the system uses this structure to return information about the user's selections. Read more on https://learn.microsoft.com. Manually copied from a 64 bit project CsWin32 generated wrapper. We can't directly use CsWin32 for this as it technically isn't compatible with AnyCPU. For our usages this works fine on both 32 bit and 64 bit. This is defined with single byte packing on 32 bit, but there are no gaps as everything naturally packs with no gaps on 32 bit. Issues would arise if this was contained in another native struct where it wouldn't start 32 bit aligned due to the single byte packing. https://github.com/microsoft/CsWin32/issues/882 Type: DWORD The structure size, in bytes. Read more on https://learn.microsoft.com. Type: HWND A handle to the window that owns the property sheet. This member must be a valid window handle; it cannot be NULL. Read more on https://learn.microsoft.com. Type: HGLOBAL A handle to a movable global memory object that contains a DEVMODE structure. If hDevMode is not NULL on input, you must allocate a movable block of memory for the DEVMODE structure and initialize its members. The PrintDlgEx function uses the input data to initialize the controls in the property sheet. When PrintDlgEx returns, the DEVMODE members indicate the user's input. If hDevMode is NULL on input, PrintDlgEx allocates memory for the DEVMODE structure, initializes its members to indicate the user's input, and returns a handle that identifies it. For more information about the hDevMode and hDevNames members, see the Remarks section at the end of this topic. Read more on https://learn.microsoft.com. Type: HGLOBAL A handle to a movable global memory object that contains a DEVNAMES structure. If hDevNames is not NULL on input, you must allocate a movable block of memory for the DEVNAMES structure and initialize its members. The PrintDlgEx function uses the input data to initialize the controls in the property sheet. When PrintDlgEx returns, the DEVNAMES members contain information for the printer chosen by the user. You can use this information to create a device context or an information context. The hDevNames member can be NULL, in which case, PrintDlgEx allocates memory for the DEVNAMES structure, initializes its members to indicate the user's input, and returns a handle that identifies it. For more information about the hDevMode and hDevNames members, see the Remarks section at the end of this topic. Read more on https://learn.microsoft.com. Type: HDC A handle to a device context or an information context, depending on whether the Flags member specifies the PD_RETURNDC or PC_RETURNIC flag. If neither flag is specified, the value of this member is undefined. If both flags are specified, PD_RETURNDC has priority. Read more on https://learn.microsoft.com. Type: DWORD Type: DWORD Type: DWORD A set of bit flags that can exclude items from the printer driver property pages in the Print property sheet. This value is used only if the PD_EXCLUSIONFLAGS flag is set in the Flags member. Exclusion flags should be used only if the item to be excluded will be included on either the General page or on an application-defined page in the Print property sheet. This member can specify the following flag. Read more on https://learn.microsoft.com. Type: DWORD On input, set this member to the initial number of page ranges specified in the lpPageRanges array. When the PrintDlgEx function returns, nPageRanges indicates the number of user-specified page ranges stored in the lpPageRanges array. If the PD_NOPAGENUMS flag is specified, this value is not valid. Read more on https://learn.microsoft.com. Type: DWORD The size, in array elements, of the lpPageRanges buffer. This value indicates the maximum number of page ranges that can be stored in the array. If the PD_NOPAGENUMS flag is specified, this value is not valid. If the PD_NOPAGENUMS flag is not specified, this value must be greater than zero. Read more on https://learn.microsoft.com. Type: LPPRINTPAGERANGE Pointer to a buffer containing an array of PRINTPAGERANGE structures. On input, the array contains the initial page ranges to display in the Pages edit control. When the PrintDlgEx function returns, the array contains the page ranges specified by the user. If the PD_NOPAGENUMS flag is specified, this value is not valid. If the PD_NOPAGENUMS flag is not specified, lpPageRanges must be non-NULL. Read more on https://learn.microsoft.com. Type: DWORD The minimum value for the page ranges specified in the Pages edit control. If the PD_NOPAGENUMS flag is specified, this value is not valid. Read more on https://learn.microsoft.com. Type: DWORD The maximum value for the page ranges specified in the Pages edit control. If the PD_NOPAGENUMS flag is specified, this value is not valid. Read more on https://learn.microsoft.com. Type: DWORD Contains the initial number of copies for the Copies edit control if hDevMode is NULL; otherwise, the dmCopies member of the DEVMODE structure contains the initial value. When PrintDlgEx returns, nCopies contains the actual number of copies the application must print. This value depends on whether the application or the printer driver is responsible for printing multiple copies. If the PD_USEDEVMODECOPIESANDCOLLATE flag is set in the Flags member, nCopies is always 1 on return, and the printer driver is responsible for printing multiple copies. If the flag is not set, the application is responsible for printing the number of copies specified by nCopies. For more information, see the description of the PD_USEDEVMODECOPIESANDCOLLATE flag. Read more on https://learn.microsoft.com. Type: HINSTANCE If the PD_ENABLEPRINTTEMPLATE flag is set in the Flags member, hInstance is a handle to the application or module instance that contains the dialog box template named by the lpPrintTemplateName member. If the PD_ENABLEPRINTTEMPLATEHANDLE flag is set in the Flags member, hInstance is a handle to a memory object containing a dialog box template. If neither of the template flags is set in the Flags member, hInstance should be NULL. Read more on https://learn.microsoft.com. Type: LPCTSTR The name of the dialog box template resource in the module identified by the hInstance member. This template replaces the default dialog box template in the lower portion of the General page. The default template contains controls similar to those of the Print dialog box. This member is ignored unless the PD_ENABLEPRINTTEMPLATE flag is set in the Flags member. Read more on https://learn.microsoft.com. Type: LPUNKNOWN A pointer to an application-defined callback object. The object should contain the IPrintDialogCallback class to receive messages for the child dialog box in the lower portion of the General page. The callback object should also contain the IObjectWithSite class to receive a pointer to the IPrintDialogServices interface. The PrintDlgEx function calls IUnknown::QueryInterface on the callback object for both IID_IPrintDialogCallback and IID_IObjectWithSite to determine which interfaces are supported. If you do not want to retrieve any of the callback information, set lpCallback to NULL. Read more on https://learn.microsoft.com. Type: DWORD The number of property page handles in the lphPropertyPages array. Read more on https://learn.microsoft.com. Type: HPROPSHEETPAGE* Contains an array of property page handles to add to the Print property sheet. The additional property pages follow the General page. Use the CreatePropertySheetPage function to create these additional pages. When the PrintDlgEx function returns, all the HPROPSHEETPAGE handles in the lphPropertyPages array have been destroyed. If nPropertyPages is zero, lphPropertyPages should be NULL. Read more on https://learn.microsoft.com. Type: DWORD The property page that is initially displayed. To display the General page, specify START_PAGE_GENERAL. Otherwise, specify the zero-based index of a property page in the array specified in the lphPropertyPages member. For consistency, it is recommended that the property sheet always be started on the General page. Read more on https://learn.microsoft.com. Type: DWORD Represents a range of pages in a print job. A print job can have more than one page range. This information is supplied in the structure when calling the function. Learn more about this API from https://learn.microsoft.com. Manually copied from a 64 bit project CsWin32 generated wrapper. We can't directly use CsWin32 for this as it technically isn't compatible with AnyCPU. For our usages this works fine on both 32 bit and 64 bit. This is defined with single byte packing on 32 bit, but there are no gaps as everything naturally packs with no gaps on 32 bit. Issues would arise if this was contained in another native struct where it wouldn't start 32 bit aligned due to the single byte packing. https://github.com/microsoft/CsWin32/issues/882 Type: DWORD The first page of the range. Read more on https://learn.microsoft.com. Type: DWORD The last page of the range. Read more on https://learn.microsoft.com. Contains information about an icon or a cursor. For monochrome icons, the hbmMask is twice the height of the icon (with the AND mask on top and the XOR mask on the bottom), and hbmColor is NULL. Also, in this case the height should be an even multiple of two. For color icons, the hbmMask and hbmColor bitmaps are the same size, each of which is the size of the icon. You can use a GetObject function to get contents of hbmMask and hbmColor in the BITMAP structure. The bitmap bits can be obtained with call to GetDIBits on the bitmaps in this structure. Read more on docs.microsoft.com. Type: BOOL Specifies whether this structure defines an icon or a cursor. A value of TRUE specifies an icon; FALSE specifies a cursor. Read more on docs.microsoft.com. Type: DWORD The x-coordinate of a cursor's hot spot. If this structure defines an icon, the hot spot is always in the center of the icon, and this member is ignored. Read more on docs.microsoft.com. Type: DWORD The y-coordinate of the cursor's hot spot. If this structure defines an icon, the hot spot is always in the center of the icon, and this member is ignored. Read more on docs.microsoft.com. Type: HBITMAP A handle to the icon monochrome mask bitmap. Read more on docs.microsoft.com. Type: HBITMAP A handle to the icon color bitmap. Read more on docs.microsoft.com. Contains message information from a thread's message queue. Learn more about this API from docs.microsoft.com. Type: HWND A handle to the window whose window procedure receives the message. This member is NULL when the message is a thread message. Read more on docs.microsoft.com. Type: UINT The message identifier. Applications can only use the low word; the high word is reserved by the system. Read more on docs.microsoft.com. Type: WPARAM Additional information about the message. The exact meaning depends on the value of the message member. Read more on docs.microsoft.com. Type: LPARAM Additional information about the message. The exact meaning depends on the value of the message member. Read more on docs.microsoft.com. Type: DWORD The time at which the message was posted. Read more on docs.microsoft.com. Type: POINT The cursor position, in screen coordinates, when the message was posted. Read more on docs.microsoft.com. Contains the scalable metrics associated with the nonclient area of a nonminimized window. (Unicode) If the iPaddedBorderWidth member of the NONCLIENTMETRICS structure is present, this structure is 4 bytes larger than for an application that is compiled with _WIN32_WINNT less than or equal to 0x0502. For more information about conditional compilation, see Using the Windows Headers. Windows Server 2003 and Windows XP/2000:  If an application that is compiled for Windows Server 2008 or Windows Vista must also run on Windows Server 2003 or Windows XP/2000, use the GetVersionEx function to check the operating system version at run time and, if the application is running on Windows Server 2003 or Windows XP/2000, subtract the size of the iPaddedBorderWidth member from the cbSize member of the NONCLIENTMETRICS structure before calling the SystemParametersInfo function. > [!NOTE] > The winuser.h header defines NONCLIENTMETRICS as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see [Conventions for Function Prototypes](/windows/win32/intl/conventions-for-function-prototypes). Read more on docs.microsoft.com. The size of the structure, in bytes. The caller must set this to sizeof(NONCLIENTMETRICS). For information about application compatibility, see Remarks. The thickness of the sizing border, in pixels. The default is 1 pixel. The width of a standard vertical scroll bar, in pixels. The height of a standard horizontal scroll bar, in pixels. The width of caption buttons, in pixels. The height of caption buttons, in pixels. A LOGFONT structure that contains information about the caption font. The width of small caption buttons, in pixels. The height of small captions, in pixels. A LOGFONT structure that contains information about the small caption font. The width of menu-bar buttons, in pixels. The height of a menu bar, in pixels. A LOGFONT structure that contains information about the font used in menu bars. A LOGFONT structure that contains information about the font used in status bars and tooltips. A LOGFONT structure that contains information about the font used in message boxes. The thickness of the padded border, in pixels. The default value is 4 pixels. The iPaddedBorderWidth and iBorderWidth members are combined for both resizable and nonresizable windows in the Windows Aero desktop experience. To compile an application that uses this member, define _WIN32_WINNT as 0x0600 or later. For more information, see Remarks. Windows Server 2003 and Windows XP/2000:  This member is not supported. Read more on docs.microsoft.com. Describes the image and accompanying text for a drop object. Some UI coloring is applied to the text in szInsert if used by specifying %1 in szMessage. The characters %% and %1 are the subset of FormatMessage markers that are processed here. Type: DROPIMAGETYPE A DROPIMAGETYPE indicating the stock image to use. Read more on docs.microsoft.com. Type: WCHAR[MAX_PATH] Text such as "Move to %1". Read more on docs.microsoft.com. Type: WCHAR[MAX_PATH] Text such as "Documents", inserted as specified by szMessage. Read more on docs.microsoft.com. Defines the CF_HDROP clipboard format. The data that follows is a double null-terminated list of file names. Learn more about this API from docs.microsoft.com. Type: DWORD The offset of the file list from the beginning of this structure, in bytes. Read more on docs.microsoft.com. Type: POINT The drop point. The coordinates depend on fNC. Read more on docs.microsoft.com. Type: BOOL A nonclient area flag. If this member is TRUE, pt specifies the screen coordinates of a point in a window's nonclient area. If it is FALSE, pt specifies the client coordinates of a point in the client area. Read more on docs.microsoft.com. Type: BOOL A value that indicates whether the file contains ANSI or Unicode characters. If the value is zero, the file contains ANSI characters. Otherwise, it contains Unicode characters. Read more on docs.microsoft.com. Values used with the DROPDESCRIPTION structure to specify the drop image. Learn more about this API from docs.microsoft.com. No drop image preference; use the default image. A red bisected circle such as that found on a "no smoking" sign. A plus sign (+) that indicates a copy operation. An arrow that indicates a move operation. An arrow that indicates a link. A tag icon that indicates that the metadata will be changed. A yellow exclamation mark that indicates that a problem has been encountered in the operation. Windows 7 and later. Use no drop image. Called by a drop source to specify whether the data object supports asynchronous data extraction. Type: BOOL VARIANT_TRUE if an asynchronous operation is supported; otherwise, VARIANT_FALSE. The default value is VARIANT_FALSE. Read more on docs.microsoft.com. Type: HRESULT If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. This method is called by the drop source to indicate that the data object supports asynchronous data extraction. Store the fDoOpAsync for later use by IDataObjectAsyncCapability::GetAsyncMode. The drop target determines whether asynchronous data extraction is supported by calling IDataObjectAsyncCapability::GetAsyncMode to retrieve the fDoOpAsync value. If fDoOpAsync is set to VARIANT_TRUE, SetAsyncMode must call IDataObjectAsyncCapability::AddRef, and store the interface pointer for use by IDataObjectAsyncCapability::EndOperation. Read more on docs.microsoft.com. Called by a drop target to determine whether the data object supports asynchronous data extraction. Type: BOOL* VARIANT_TRUE if an asynchronous operation is supported; otherwise, VARIANT_FALSE. Read more on docs.microsoft.com. Type: HRESULT If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. The purpose of this method is to give the drop target the value of the IDataObjectAsyncCapability::SetAsyncMode method's fDoOpAsync parameter. This parameter is set to VARIANT_FALSE by default. If the data object supports asynchronous data extraction, it must call IDataObjectAsyncCapability::SetAsyncMode and set fDoOpAsync to VARIANT_TRUE. Called by a drop target to indicate that asynchronous data extraction is starting. Type: IBindCtx* Reserved. Set this value to nullptr. Read more on docs.microsoft.com. Type: HRESULT If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. The drop target calls this method to notify the data object that asynchronous data extraction is starting. The method should store this information so that it can be returned by IDataObjectAsyncCapability::InOperation. Once StartOperation has been called, the drop target returns the IDropTarget::Drop call as it would for normal synchronous data extraction. Called by the drop source to determine whether the target is extracting data asynchronously. Type: BOOL* VARIANT_TRUE if data extraction is being handled asynchronously; otherwise, VARIANT_FALSE. Read more on docs.microsoft.com. Type: HRESULT If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. This method is called by the drop source after DoDragDrop returns. The pfInAsyncOp parameter should be set to VARIANT_TRUE only if the drop target has called IDataObjectAsyncCapability::StartOperation. Notifies the data object that the asynchronous data extraction has ended. Type: HRESULT Indicates the outcome of the data extraction. Set this value to S_OK if successful, or a COM error code otherwise. Read more on docs.microsoft.com. Type: IBindCtx* Reserved. Set to nullptr. Read more on docs.microsoft.com. Type: DWORD A DROPEFFECT value that indicates the result of an optimized move. This should be the same value that would be passed to the data object as a CFSTR_PERFORMEDDROPEFFECT format with a normal data extraction operation. Read more on docs.microsoft.com. Type: HRESULT If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. EndOperation retrieves the IDataObjectAsyncCapability pointer stored by IDataObjectAsyncCapability::SetAsyncMode and passes its parameter values to that interface's IDataObjectAsyncCapability::EndOperation method. EndOperation then releases the IDataObjectAsyncCapability pointer. EndOperation is also responsible for any associated clean-up operations. When finished, EndOperation should notify the drop source through a private interface. Read more on docs.microsoft.com. The IID guid for this interface. {3d8b0590-f691-11d2-8ea9-006097df5bd4} Initializes the drag-image manager for a windowless control. Type: LPSHDRAGIMAGE The SHDRAGIMAGE structure that contains information about the bitmap. Read more on docs.microsoft.com. Type: IDataObject* A pointer to the data object's IDataObject interface. Read more on docs.microsoft.com. Type: HRESULT If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. Because InitializeFromBitmap always performs the RGB multiplication step in calculating the alpha value, you should always pass a bitmap without premultiplied alpha blending. Note that no error will result from passing the method a bitmap with premultiplied alpha blending, but this method will multiply it again, doubling the resulting alpha value. Initializes the drag-image manager for a control with a window. Type: HWND A handle to the window that receives the DI_GETDRAGIMAGE message. This value can be NULL. Read more on docs.microsoft.com. Type: POINT* A pointer to a POINT structure that specifies the location of the cursor within the drag image. The structure should contain the offset from the upper-left corner of the drag image to the location of the cursor. This value can be NULL. Read more on docs.microsoft.com. Type: IDataObject* A pointer to the data object's IDataObject interface. Read more on docs.microsoft.com. Type: HRESULT If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. The DI_GETDRAGIMAGE message allows you to source a drag image from a custom control. It is defined in Shlobj.h and must be registered with RegisterWindowMessage. When the window specified by hwnd receives the DI_GETDRAGIMAGE message, the lParam value holds a pointer to an SHDRAGIMAGE structure. The handler should fill the structure with the drag image bitmap information. The IID guid for this interface. {de5bf786-477a-11d2-839d-00c04fd918d0} Sets the characteristics of a drag-and-drop operation over an IDragSourceHelper object. Type: DWORD The flags that determine the characteristics of a drag-and-drop operation over an IDragSourceHelper object. Read more on docs.microsoft.com. Type: HRESULT If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. Learn more about this API from docs.microsoft.com. The IID guid for this interface. {83e07d0d-0c5f-4163-bf1a-60b274051e40} Notifies the drag-image manager that the drop target's IDropTarget::DragEnter method has been called. Type: HWND The target's window handle. Read more on docs.microsoft.com. Type: IDataObject* A pointer to the data object's IDataObject interface. Read more on docs.microsoft.com. Type: POINT* The POINT structure pointer that was received in the IDropTarget::DragEnter method's pt parameter. Read more on docs.microsoft.com. Type: DWORD The value pointed to by the IDropTarget::DragEnter method's pdwEffect parameter. Read more on docs.microsoft.com. Type: HRESULT Returns S_OK if successful, or a COM error value otherwise. This method is called by a drop target when its IDropTarget::DragEnter method is called. It notifies the drag-image manager that the drop target has been entered, and provides it with the information needed to display the drag image. Notifies the drag-image manager that the drop target's IDropTarget::DragLeave method has been called. Type: HRESULT Returns S_OK if successful, or a COM error value otherwise. This method is called by a drop target when its IDropTarget::DragLeave method is called. It notifies the drag-image manager that the cursor has left the drop target. Notifies the drag-image manager that the drop target's IDropTarget::DragOver method has been called. Type: POINT* The POINT structure pointer that was received in the IDropTarget::DragOver method's pt parameter. Read more on docs.microsoft.com. Type: DWORD The value pointed to by the IDropTarget::DragOver method's pdwEffect parameter. Read more on docs.microsoft.com. Type: HRESULT Returns S_OK if successful, or a COM error value otherwise. This method is called by a drop target when its IDropTarget::DragOver method is called. It notifies the drag-image manager that the cursor position has changed and provides it with the information needed to display the drag image. Notifies the drag-image manager that the drop target's IDropTarget::Drop method has been called. Type: IDataObject* A pointer to the data object's IDataObject interface. Read more on docs.microsoft.com. Type: POINT* A POINT structure pointer that was received in the IDropTarget::Drop method's pt parameter. Read more on docs.microsoft.com. Type: DWORD The value pointed to by the IDropTarget::Drop method's pdwEffect parameter. Read more on docs.microsoft.com. Type: HRESULT Returns S_OK if successful, or a COM error value otherwise. This method is called by a drop target when its IDropTarget::Drop method is called. It notifies the drag-image manager that the object has been dropped, and provides it with the information needed to display the drag image. Notifies the drag-image manager to show or hide the drag image. Type: BOOL A boolean value that is set to TRUE to show the drag image, and FALSE to hide it. Read more on docs.microsoft.com. Type: HRESULT Returns S_OK if successful, or a COM error value otherwise. This method is used when dragging over a target window in a low color-depth video mode. It allows the target to notify the drag-image manager to hide the drag image while it is painting the window. While you are painting a window that is currently being dragged over, hide the drag image by calling Show with fShow set to FALSE. Once the window has been painted, display the drag image again by calling Show with fShow set to TRUE. The IID guid for this interface. {4657278b-411b-11d2-839a-00c04fd918d0} Contains the information needed to create a drag image. In Windows Vista this structure is defined in Shobjidl.idl. Prior to that, it was defined in Shlobj.h. Use the following procedure to create the drag image. This doc was truncated. Read more on docs.microsoft.com. Type: SIZE A SIZE structure with the length and width of the drag image. Read more on docs.microsoft.com. Type: POINT A POINT structure that specifies the location of the cursor within the drag image. The structure should contain the offset from the upper-left corner of the drag image to the location of the cursor. Read more on docs.microsoft.com. Type: HBITMAP The drag image's bitmap handle. Read more on docs.microsoft.com. Type: COLORREF The color used by the control to fill the background of the drag image. Read more on docs.microsoft.com. Contains information about the high contrast accessibility feature. (Unicode) An application uses this structure when calling the[SystemParametersInfoW function](nf-winuser-systemparametersinfow.md) with the SPI_GETHIGHCONTRAST or SPI_SETHIGHCONTRAST value. When using SPI_GETHIGHCONTRAST, an application must specify the cbSize member of the HIGHCONTRAST structure; the SystemParametersInfo function fills the remaining members. An application must specify all structure members when using the SPI_SETHIGHCONTRAST value. > [!NOTE] > The winuser.h header defines HIGHCONTRAST as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see [Conventions for Function Prototypes](/windows/win32/intl/conventions-for-function-prototypes). Read more on docs.microsoft.com. Type: UINT Specifies the size, in bytes, of this structure. Read more on docs.microsoft.com. Type: DWORD Type: LPTSTR Points to a string that contains the name of the color scheme that will be set to the default scheme. The system allocates this buffer, free it with LocalFree. Read more on docs.microsoft.com. The length of the inline array. Gets a ref to an individual element of the inline array. ⚠ Important ⚠: When this struct is on the stack, do not let the returned reference outlive the stack frame that defines it. Gets this inline array as a span. ⚠ Important ⚠: When this struct is on the stack, do not let the returned span outlive the stack frame that defines it. Gets this inline array as a span. ⚠ Important ⚠: When this struct is on the stack, do not let the returned span outlive the stack frame that defines it. The length of the inline array. Gets a ref to an individual element of the inline array. ⚠ Important ⚠: When this struct is on the stack, do not let the returned reference outlive the stack frame that defines it. Gets this inline array as a span. ⚠ Important ⚠: When this struct is on the stack, do not let the returned span outlive the stack frame that defines it. Gets this inline array as a span. ⚠ Important ⚠: When this struct is on the stack, do not let the returned span outlive the stack frame that defines it. Copies the fixed array to a new string up to the specified length regardless of whether there are null terminating characters. Thrown when is less than 0 or greater than . Copies the fixed array to a new string, stopping before the first null terminator character or at the end of the fixed array (whichever is shorter). The length of the inline array. Gets a ref to an individual element of the inline array. ⚠ Important ⚠: When this struct is on the stack, do not let the returned reference outlive the stack frame that defines it. Gets this inline array as a span. ⚠ Important ⚠: When this struct is on the stack, do not let the returned span outlive the stack frame that defines it. Gets this inline array as a span. ⚠ Important ⚠: When this struct is on the stack, do not let the returned span outlive the stack frame that defines it. Copies the fixed array to a new string up to the specified length regardless of whether there are null terminating characters. Thrown when is less than 0 or greater than . Copies the fixed array to a new string, stopping before the first null terminator character or at the end of the fixed array (whichever is shorter). The IID guid for this interface. The reference that is returned comes from a permanent memory address, and is therefore safe to convert to a pointer and pass around or hold long-term. Non generic interface that allows constraining against a COM wrapper type directly. COM structs should implement . Windows Forms implementation. Deriving from allows us to leverage the functionality the runtime has implemented for source generated "RCW"s, including support for adaption when built-in COM support is available (EnableGeneratedComInterfaceComImportInterop). It isn't immediately clear how we could merge with this as there is no strategy for . We rely on to apply the needed vtable functionality and it doesn't appear that we can apply without manually implementing (or source generating) on our exposed classes. The implementation for WinForm's COM interop usages. For the given pointer unwrap the associated managed object and use it to invoke . Handles exceptions and converts to . For the given pointer unwrap the associated managed object and use it to invoke .