YourPhoneAppProxy.Core

Defines the source generated JSON serialization contract metadata for a given type.

The default associated with a default instance.

The source-generated options associated with this context.

Any app launch that is initiated from Your Phone. This includes AppsList, Phone screen link, and Nav bar Phone screen launch Only available for devices that support Part C MultipleApps entry points.

Any app launch that is initiated from Your Phone. This includes AppsList, Phone screen link, and Nav bar Phone screen launch Available for devices that do not support MultipleApps, but do support phone screen apps.

A framework-agnostic command implementation that wraps delegates for execution and can-execute logic. This command does not depend on any UI framework types and can be used in Core projects. Use CommandAdapter to convert this to a RelayCommand for UI binding.

Adding an image preview image to drag drop, depending on isMultiple and file extension

Adding an image preview when dealing with multiple images

dataObject telemetryFactory

Add an image preview form extension (when dealing with a single file)

dataObject extension including dot ex: ".jpg" telemetryFactory

Set the actual shadow into the dataObject

bitmap dataObject telemetryFactory

Sets the drop description for the drag image manager.

The DataObject to set. The type of the drop image. The format string for the description. The parameter for the drop description. When setting the drop description, the text can be set in two part, which will be rendered slightly differently to distinguish the description from the subject. For example, the format can be set as "Move to %1" and the insert as "Temp". When rendered, the "%1" in format will be replaced with "Temp", but "Temp" will be rendered slightly different from "Move to ".

Sets the drop description for the drag image manager.

The DataObject to set. The drop description.

Gets the DropDescription format data.

The DataObject. The DropDescription, if set.

Fills a FORMATETC structure.

The format name. The accepted TYMED. The structure to fill.

Get icon index from extension name

extension with dot ex: ".jpg" telemetryFactory Icon index

Get an icon formIImage

IImage telemetryFactory 256*256 icon

Showing the drop description or not, (not yet supported)

bool

Invalidate the image medium

dataObject

Get the pointer from medium

medium IntPtr

Gets the extension name from a path

list of file names ".multiple" if dealing with multiple files, else the extension

Returns true iff the HRESULT is a success code.

HRESULT to check. True if a success code.

Creates a CLSID_DragDropHelper COM object and returns the requested interface. Uses StrategyBasedComWrappers for RCW creation compatible with DisableRuntimeMarshalling.

Drag-drop operation canceled

Class implementing drag/drop and clipboard support for virtual files. Also offers an alternate interface to the IDataObject interface.

Uses [GeneratedComClass] with StrategyBasedComWrappers for Native AOT compatibility. Source generator creates vtables at compile-time for DisableRuntimeMarshalling support.

Error Ole Advise Not Supported

Invalid tymed

Invalid FORMATETC structure

Invalid aspect(s)

Drag Use the default cursor

Drag-drop operation canceled

Successful drop took place

Gets or sets a value indicating whether the data object can be used asynchronously.

Identifier for CFSTR_FILECONTENTS.

Identifier for CFSTR_FILEDESCRIPTORW.

Identifier for CFSTR_PASTESUCCEEDED.

Identifier for CFSTR_PERFORMEDDROPEFFECT.

Identifier for CFSTR_PREFERREDDROPEFFECT.

In-order list of registered data objects.

Tracks whether an asynchronous operation is ongoing.

Stores the user-specified start action.

Stores the user-specified end action.

Initializes a new instance of the class.

Optional action to run at the start of the data transfer. Optional action to run at the end of the data transfer.

Creates a connection between a data object and an advisory sink.

Destroys a notification connection that had been previously established.

Creates an object that can be used to enumerate the current advisory connections.

Creates an object for enumerating the FORMATETC structures for a data object.

Provides a standard FORMATETC structure that is logically equivalent to a more complex structure.

Obtains data from a source data object.

Obtains data from a source data object (alternative form).

Determines whether the data object is capable of rendering the data described in the FORMATETC structure.

Transfers data to the object that implements this method.

Provides data for the specified data format (HGLOBAL).

Data format. Sequence of data.

Provides data for the specified data format and index (ISTREAM).

Data format. Index of data. Action generating the data. Uses Stream instead of IEnumerable(T) because Stream is more likely to be natural for the expected scenarios.

SetData for objects that don't require delayed rendering

data format should we release medium The pair.

Provides data for the specified data format (FILEGROUPDESCRIPTOR/FILEDESCRIPTOR)

Collection of virtual files.

Gets or sets the CFSTR_PASTESUCCEEDED value for the object.

Gets or sets the CFSTR_PERFORMEDDROPEFFECT value for the object.

Gets or sets the CFSTR_PREFERREDDROPEFFECT value for the object.

Gets the DROPEFFECT value (if any) previously set on the object.

Clipboard format. DROPEFFECT value or null.

Called by a drop source to specify whether the data object supports asynchronous data extraction.

A Boolean value that is set to VARIANT_TRUE to indicate that an asynchronous operation is supported, or VARIANT_FALSE otherwise.

Called by a drop target to determine whether the data object supports asynchronous data extraction.

A Boolean value that is set to VARIANT_TRUE to indicate that an asynchronous operation is supported, or VARIANT_FALSE otherwise.

Called by a drop target to indicate that asynchronous data extraction is starting.

Reserved. Set this value to NULL.

Called by the drop source to determine whether the target is extracting data asynchronously.

Set to VARIANT_TRUE if data extraction is being handled asynchronously, or VARIANT_FALSE otherwise.

Notifies the data object that that asynchronous data extraction has ended.

An HRESULT value that indicates the outcome of the data extraction. Set to S_OK if successful, or a COM error code otherwise. Reserved. Set to NULL. 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.

Returns true iff the HRESULT is a success code.

HRESULT to check. True iff a success code.

Returns the in-memory representation of an interop structure.

The type of structure to convert. Structure to return. In-memory representation of structure.

Class representing a virtual file for use by drag/drop or the clipboard.

Gets or sets the name of the file.

Gets or sets the (optional) length of the file.

Gets or sets the (optional) change time of the file.

Gets or sets an Action that returns the contents of the file.

Class representing the result of writting the Stream

Class representing the result of a SetData call.

FORMATETC structure for the data.

Func returning the data as an IntPtr and an HRESULT success code.

Explecit Medium, when ignoring delayed rendering

Should we release medium

Gets the value of the current Tuple(T1, T2) object's first component.

Gets the value of the current Tuple(T1, T2) object's second component.

Initializes a new instance of the class. Initializes a new instance of the Tuple(T1, T2) class.

The value of the tuple's first component. The value of the tuple's second component.

Simple class that exposes a write-only IStream as a Stream.

IStream COM interface.

Initializes a new instance of the class.

IStream COM interface.

Gets a value indicating whether the current stream supports reading.

Gets a value indicating whether the current stream supports seeking.

Gets a value indicating whether the current stream supports writing.

Clears all buffers for this stream and causes any buffered data to be written to the underlying device.

Gets the length in bytes of the stream.

Gets or sets the position within the current stream.

Reads a sequence of bytes from the current stream and advances the position within the stream by the number of bytes read.

An array of bytes. When this method returns, the buffer contains the specified byte array with the values between offset and (offset + count - 1) replaced by the bytes read from the current source. The zero-based byte offset in buffer at which to begin storing the data read from the current stream. The maximum number of bytes to be read from the current stream. The total number of bytes read into the buffer. This can be less than the number of bytes requested if that many bytes are not currently available, or zero (0) if the end of the stream has been reached.

Sets the position within the current stream.

A byte offset relative to the origin parameter. A value of type SeekOrigin indicating the reference point used to obtain the new position. The new position within the current stream.

Sets the length of the current stream.

The desired length of the current stream in bytes.

Writes a sequence of bytes to the current stream and advances the current position within this stream by the number of bytes written.

An array of bytes. This method copies count bytes from buffer to the current stream. The zero-based byte offset in buffer at which to begin copying bytes to the current stream. The number of bytes to be written to the current stream.

Initiates a drag-and-drop operation.

A data object that contains the data being dragged. One of the DROPEFFECT values that specifies permitted effects of the drag-and-drop operation. telemetryFactory One of the DROPEFFECT values that specifies the final effect that was performed during the drag-and-drop operation. Call this method instead of System.Windows.DragDrop.DoDragDrop because this method handles IDataObject better.

Contains the methods for generating visual feedback to the end user and for canceling or completing the drag-and-drop operation.

Determines whether a drag-and-drop operation should continue.

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 returns S_OK/DRAGDROP_S_DROP/DRAGDROP_S_CANCEL on success.

Gives visual feedback to an end user during a drag-and-drop operation.

The DROPEFFECT value returned by the most recent call to IDropTarget::DragEnter, IDropTarget::DragOver, or IDropTarget::DragLeave. This method returns S_OK on success.

Helper class containing extended key definitions that can be used across the Core project.

Gets a set of keys that trigger the isExtended flag.

Does the current keyboard contain the AltGr key

bool

Is the current system language an IME language?

bool

Indicates if the mouse is being pressed during drag and drop. This is checked when dragging over some windows that request data on drag over.

Gets a set of keys that trigger the isExtended flag

Try to get a PointerEventArgs

Current window properties wParam from WndProc WindowMessages out pointerEventArgs success/failure

Creates a mouse PointerEventArgs directly from WinUI event data. No Win32 GetPointerInfo call is made; the update kind and position are provided by the caller. The wheel deltas are adjusted for the system scroll-lines setting.

Creates a touch PointerEventArgs directly from WinUI event data. No Win32 GetPointerTouchInfo call is made.

Creates a pen PointerEventArgs directly from WinUI event data. No Win32 GetPointerPenInfo call is made.

Base class for keyboard event arguments that works across both WPF and WinUI3. This class contains the essential keyboard event information needed for input handling. This class wraps System.Windows.Input.KeyEventArgs for WPF.

Represents the key enumeration for keyboard inputs. These are common key values used across different UI frameworks.

Represents the different key states.

Represents modifier keys that can be pressed along with other keys.

Gets the first free index in the map

int

Tries to retrieve the fingerId associated with the Pointer Id

Pointer Id out fingerId result success / failure

Tries to remove the fingerId from the finger map

PointerId out fingerId removed success / failure

Source-generated IDataObject COM interface for Native AOT and DisableRuntimeMarshalling.

Definition of the IAsyncOperation COM interface.

Pseudo-public because VirtualFileDataObject implements it.

Initializes the drag-image manager for a control with a bitmap.

Initializes the drag-image manager for a control with a window.

IStream interface for reading and writing data to stream objects.

Native methods for drag and drop functionality. Refactored to use CsWin32-generated APIs where possible.

Gets the COM interface pointer from an RCW created by UniqueComInterfaceMarshaller.

Contains a 64-bit value representing the number of 100-nanosecond intervals since January 1, 1601 (UTC).

Native-compatible DropDescription struct using fixed char buffers. Use this when DisableRuntimeMarshallingAttribute is applied.

Window arrangement reduces the number of mouse, pen, or touch interactions needed to move and size top-level windows by simplifying the default behavior of a window when it is dragged or sized

Allow a window to be vertically maximized when it is sized to the top or bottom of the monitor

Allow a window to be docked when it is moved to the top, left, or right docking targets on a monitor or monitor array

Allow a maximized window to be restored when its caption bar is dragged

Used to shutdown app and call Current.Shutdown at the end to avoid any time limits when closing the app

Exit reason If should call Application.Shutdown after cleanup. Default value is true. Task

For background threads unhandled exceptions

Mapping for app theme represented at Shell.MMX\apps\yourphone\uap\YourPhone\YourPhone.Contracts.Shell\AppTheme.idl Keep in sync if possible

Ensures that an Action logs and continues on failures.

Helper extension method for building out logging strings. This method will only append the new string if it is not null or empty. Else it will return the original string. Has optional parameters for a label and a separator as well. (e.g. AppendIfNotNullOrEmpty("workflow: permission", "blob", "channel") returns "workflow: permission, channel: blob")

the original string as extended the string to be appended if not null or empty the label that will come before the appended string, default is null which would be omitted the separator used between appending, default is "," the original string plus the appended string with optional label if not null or empty, otherwise the original string

Ensures that an async operation that is not await'ed logs and continues on failures.

Ensures that an async operation that is not await'ed logs and continues on failures

When using await in a ContinueWith, the return is a Task{Task} and it needs to be unwrapped.

Ensures that an async operation that is not await'ed FailsFast on failures

Ensures that an async operation that is not await'ed FailsFast on failures and stops the provided health activity

Ensures that an async operation that is not await'ed FailsFast on failures

When using await in a ContinueWith, the return is a Task{Task} and it needs to be unwrapped.

Ensures that an async operation that is not await'ed FailsFast on failures and stops the provided health activity

When using await in a ContinueWith, the return is a Task{Task} and it needs to be unwrapped.

Carries pre-computed display transform state for the SwapChainPanel path, mirroring the DCompositionHelper rotate * translate * scale matrix chain.

Rotation angle in degrees (0, -90, -180, -270).

Pre-scale X translation in physical pixels.

Pre-scale Y translation in physical pixels.

Horizontal scale factor (container width px / effective video width px).

Vertical scale factor (container height px / effective video height px).

Native (pre-rotation) video width in physical pixels.

Native (pre-rotation) video height in physical pixels.

Defines the source generated JSON serialization contract metadata for a given type.

The default associated with a default instance.

The source-generated options associated with this context.

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.

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.

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.

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.

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.

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)

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)

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)

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}

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 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}

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.

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.

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}

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}

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}

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}

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.

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.

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.

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.

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.

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}

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}

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.

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.

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. 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.

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 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 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.

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.

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).

Represents a Win32 handle that can be closed with .

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.

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 information about a low-level mouse input event.

Learn more about this API from docs.microsoft.com.

Type: POINT The x- and y-coordinates of the cursor, in per-monitor-aware screen coordinates. Read more on docs.microsoft.com.

Type: DWORD If the message is WM_MOUSEWHEEL, the high-order word of this member is the wheel delta. The low-order word is reserved. A positive value indicates that the wheel was rotated forward, away from the user; a negative value indicates that the wheel was rotated backward, toward the user. One wheel click is defined as WHEEL_DELTA, which is 120. Read more on docs.microsoft.com.

Type: DWORD The event-injected flags. An application can use the following values to test the flags. Testing LLMHF_INJECTED (bit 0) will tell you whether the event was injected. If it was, then testing LLMHF_LOWER_IL_INJECTED (bit 1) will tell you whether or not the event was injected from a process running at lower integrity level. This doc was truncated. Read more on docs.microsoft.com.

Type: DWORD The time stamp for this message. Read more on docs.microsoft.com.

Type: ULONG_PTR Additional information associated with the message. Read more on docs.microsoft.com.

Contains information about an image in an image list. This structure is used with the IImageList::GetImageInfo function. (IMAGEINFO)

Learn more about this API from docs.microsoft.com.

Type: HBITMAP A handle to the bitmap that contains the images. Read more on docs.microsoft.com.

Type: HBITMAP A handle to a monochrome bitmap that contains the masks for the images. If the image list does not contain a mask, this member is NULL. Read more on docs.microsoft.com.

Type: int Not used. This member should always be zero. Read more on docs.microsoft.com.

Type: RECT The bounding rectangle of the specified image within the bitmap specified by hbmImage. Read more on docs.microsoft.com.

Contains information about an image list draw operation and is used with the IImageList::Draw function. (IMAGELISTDRAWPARAMS)

An overlay image is an image that is drawn on top of the primary image specified in the i member of this structure. To specify an overlay image, use the bitwise OR operator to combine fStyle with the INDEXTOOVERLAYMASK macro, passing the one-based index of the overlay image in the macro. This image must have been previously specified as an overlay image using the ImageList_SetOverlayImage API. To extract the overlay image from the fStyle, use the bitwise AND operator to mask fStyle with the ILD_OVERLAYMASK value. Comctl32.dll version 6 is not redistributable.. To use Comctl32.dll version 6, you must specify it in a manifest. For more information on manifests, see Enabling Visual Styles. Read more on docs.microsoft.com.

Type: DWORD The size of this structure, in bytes. Read more on docs.microsoft.com.

Type: HIMAGELIST A handle to the image list that contains the image to be drawn. Read more on docs.microsoft.com.

Type: int The zero-based index of the image to be drawn. Read more on docs.microsoft.com.

Type: HDC A handle to the destination device context. Read more on docs.microsoft.com.

Type: int The x-coordinate that specifies where the image is drawn. Read more on docs.microsoft.com.

Type: int The y-coordinate that specifies where the image is drawn. Read more on docs.microsoft.com.

Type: int A value that specifies the number of pixels to draw, relative to the upper-left corner of the drawing operation as specified by xBitmap and yBitmap. If cx and cy are zero, then Draw draws the entire valid section. The method does not ensure that the parameters are valid. Read more on docs.microsoft.com.

Type: int The x-coordinate that specifies the upper-left corner of the drawing operation in reference to the image itself. Pixels of the image that are to the left of xBitmap and above yBitmap do not appear. Read more on docs.microsoft.com.

Type: int The y-coordinate that specifies the upper-left corner of the drawing operation in reference to the image itself. Pixels of the image that are to the left of xBitmap and above yBitmap do not appear. Read more on docs.microsoft.com.

Type: COLORREF

Type: UINT A flag specifying the drawing style and, optionally, the overlay image. See the comments section at the end of this topic for information on the overlay image. This member can contain one or more image list drawing flags. Read more on docs.microsoft.com.

Type: DWORD A value specifying a raster operation code. These codes define how the color data for the source rectangle will be combined with the color data for the destination rectangle to achieve the final color. This member is ignored if fStyle does not include the ILD_ROP flag. Some common raster operation codes include: This doc was truncated. Read more on docs.microsoft.com.

Type: DWORD A flag that specifies the drawing state. This member can contain one or more image list state flags. You must use comctl32.dll version 6 to use this member. See the Remarks. Read more on docs.microsoft.com.

Type: DWORD Used with the alpha blending effect. When used with ILS_ALPHA, this member holds the value for the alpha channel. This value can be from 0 to 255, with 0 being completely transparent, and 255 being completely opaque. You must use comctl32.dll version 6 to use this member. See the Remarks. Read more on docs.microsoft.com.

Type: DWORD A color used for the glow and shadow effects. You must use comctl32.dll version 6 to use this member. See the Remarks. Read more on docs.microsoft.com.

Identifies a change in the state of a button associated with a pointer.

Learn more about this API from docs.microsoft.com.

No change in button state.

The first button (see POINTER_FLAG_FIRSTBUTTON) transitioned to a pressed state.

The first button (see POINTER_FLAG_FIRSTBUTTON) transitioned to a released state.

The second button (see POINTER_FLAG_SECONDBUTTON) transitioned to a pressed state.

The second button (see POINTER_FLAG_SECONDBUTTON) transitioned to a released state.

The third button (see POINTER_FLAG_THIRDBUTTON) transitioned to a pressed state.

The third button (see POINTER_FLAG_THIRDBUTTON) transitioned to a released state.

The fourth button (see POINTER_FLAG_FOURTHBUTTON) transitioned to a pressed state.

The fourth button (see POINTER_FLAG_FOURTHBUTTON) transitioned to a released state.

The fifth button (see POINTER_FLAG_FIFTHBUTTON) transitioned to a pressed state.

The fifth button (see POINTER_FLAG_FIFTHBUTTON) transitioned to a released state.

Contains basic pointer information common to all pointer types. Applications can retrieve this information using the GetPointerInfo, GetPointerFrameInfo, GetPointerInfoHistory and GetPointerFrameInfoHistory functions.

Learn more about this API from docs.microsoft.com.

Type: POINTER_INPUT_TYPE A value from the POINTER_INPUT_TYPE enumeration that specifies the pointer type. Read more on docs.microsoft.com.

Type: UINT32 An identifier that uniquely identifies a pointer during its lifetime. A pointer comes into existence when it is first detected and ends its existence when it goes out of detection range. Note that if a physical entity (finger or pen) goes out of detection range and then returns to be detected again, it is treated as a new pointer and may be assigned a new pointer identifier. Read more on docs.microsoft.com.

Type: UINT32 An identifier common to multiple pointers for which the source device reported an update in a single input frame. For example, a parallel-mode multi-touch digitizer may report the positions of multiple touch contacts in a single update to the system. Note that frame identifier is assigned as input is reported to the system for all pointers across all devices. Therefore, this field may not contain strictly sequential values in a single series of messages that a window receives. However, this field will contain the same numerical value for all input updates that were reported in the same input frame by a single device. Read more on docs.microsoft.com.

Type: POINTER_FLAGS May be any reasonable combination of flags from the Pointer Flags constants. Read more on docs.microsoft.com.

Type: HANDLE Handle to the source device that can be used in calls to the raw input device API and the digitizer device API. Read more on docs.microsoft.com.

Type: HWND Window to which this message was targeted. If the pointer is captured, either implicitly by virtue of having made contact over this window or explicitly using the pointer capture API, this is the capture window. If the pointer is uncaptured, this is the window over which the pointer was when this message was generated. Read more on docs.microsoft.com.

Type: POINT The predicted screen coordinates of the pointer, in pixels. The predicted value is based on the pointer position reported by the digitizer and the motion of the pointer. This correction can compensate for visual lag due to inherent delays in sensing and processing the pointer location on the digitizer. This is applicable to pointers of type PT_TOUCH. For other pointer types, the predicted value will be the same as the non-predicted value (see ptPixelLocationRaw). Read more on docs.microsoft.com.

Type: POINT The predicted screen coordinates of the pointer, in HIMETRIC units. The predicted value is based on the pointer position reported by the digitizer and the motion of the pointer. This correction can compensate for visual lag due to inherent delays in sensing and processing the pointer location on the digitizer. This is applicable to pointers of type PT_TOUCH. For other pointer types, the predicted value will be the same as the non-predicted value (see ptHimetricLocationRaw). Read more on docs.microsoft.com.

Type: POINT The screen coordinates of the pointer, in pixels. For adjusted screen coordinates, see ptPixelLocation. Read more on docs.microsoft.com.

Type: POINT The screen coordinates of the pointer, in HIMETRIC units. For adjusted screen coordinates, see ptHimetricLocation. Read more on docs.microsoft.com.

Type: DWORD 0 or the time stamp of the message, based on the system tick count when the message was received. The application can specify the input time stamp in either dwTime or PerformanceCount. The value cannot be more recent than the current tick count or QueryPerformanceCount (QPC) value of the injection thread. Once a frame is injected with a time stamp, all subsequent frames must include a timestamp until all contacts in the frame go to an UP state. The custom timestamp value must also be provided for the first element in the contacts array. The time stamp values after the first element are ignored. The custom timestamp value must increment in every injection frame. When PerformanceCount is specified, the time stamp will be converted to the current time in .1 millisecond resolution upon actual injection. If a custom PerformanceCount resulted in the same .1 millisecond window from the previous injection, ERROR_NOT_READY is returned and injection will not occur. While injection will not be invalidated immediately by the error, the next successful injection must have a PerformanceCount value that is at least 0.1 millisecond from the previously successful injection. This is also true if dwTime is used. If both dwTime and PerformanceCount are specified in InjectTouchInput, ERROR_INVALID_PARAMETER is returned. InjectTouchInput cannot switch between dwTime and PerformanceCount once injection has started. If neither dwTime and PerformanceCount are specified, InjectTouchInput allocates the timestamp based on the timing of the call. If InjectTouchInput calls are repeatedly less than 0.1 millisecond apart, ERROR_NOT_READY might be returned. The error will not invalidate the input immediately, but the injection application needs to retry the same frame again for injection to succeed. Read more on docs.microsoft.com.

Type: UINT32 Count of inputs that were coalesced into this message. This count matches the total count of entries that can be returned by a call to GetPointerInfoHistory. If no coalescing occurred, this count is 1 for the single input represented by the message. Read more on docs.microsoft.com.

Type: DWORD

Type: UINT64 The value of the high-resolution performance counter when the pointer message was received (high-precision, 64 bit alternative to dwTime). The value can be calibrated when the touch digitizer hardware supports the scan timestamp information in its input report. Read more on docs.microsoft.com.

Type: POINTER_BUTTON_CHANGE_TYPE A value from the POINTER_BUTTON_CHANGE_TYPE enumeration that specifies the change in button state between this input and the previous input. Read more on docs.microsoft.com.

Defines basic pen information common to all pointer types.

Applications can retrieve this information using the GetPointerPenInfo, GetPointerFramePenInfo, GetPointerPenInfoHistory and GetPointerFramePenInfoHistory API functions.

Type: POINTER_INFO An embedded POINTER_INFO structure. Read more on docs.microsoft.com.

Type: PEN_FLAGS The pen flag. This member can be zero or any reasonable combination of the values from the Pen Flags constants. Read more on docs.microsoft.com.

Type: PEN_MASK The pen mask. This member can be zero or any reasonable combination of the values from the Pen Mask constants. Read more on docs.microsoft.com.

Type: UINT32 A pen pressure normalized to a range between 0 and 1024. The default is 0 if the device does not report pressure. Read more on docs.microsoft.com.

Type: UINT32 The clockwise rotation, or twist, of the pointer normalized in a range of 0 to 359. The default is 0. Read more on docs.microsoft.com.

Type: INT32 The angle of tilt of the pointer along the x-axis in a range of -90 to +90, with a positive value indicating a tilt to the right. The default is 0. Read more on docs.microsoft.com.

Type: INT32 The angle of tilt of the pointer along the y-axis in a range of -90 to +90, with a positive value indicating a tilt toward the user. The default is 0. Read more on docs.microsoft.com.

Defines basic touch information common to all pointer types.

Learn more about this API from docs.microsoft.com.

Type: **[POINTER_INFO](ns-winuser-pointer_info.md)** An embedded [POINTER_INFO](ns-winuser-pointer_info.md) header structure. Read more on docs.microsoft.com.

Type: **[Touch Flags](/windows/win32/inputmsg/touch-flags-constants)** Currently none. Read more on docs.microsoft.com.

Type: **[Touch Mask](/windows/win32/inputmsg/touch-mask-constants)** Indicates which of the optional fields contain valid values. The member can be zero or any combination of the values from the [Touch Mask](/windows/win32/inputmsg/touch-mask-constants) constants. Read more on docs.microsoft.com.

Type: **RECT** The predicted screen coordinates of the contact area, in pixels. By default, if the device does not report a contact area, this field defaults to a 0-by-0 rectangle centered around the pointer location. The predicted value is based on the pointer position reported by the digitizer and the motion of the pointer. This correction can compensate for visual lag due to inherent delays in sensing and processing the pointer location on the digitizer. This is applicable to pointers of type [PT_TOUCH](ne-winuser-tagpointer_input_type.md). Read more on docs.microsoft.com.

Type: **RECT** The raw screen coordinates of the contact area, in pixels. For adjusted screen coordinates, see **rcContact**. Read more on docs.microsoft.com.

Type: **UINT32** A pointer orientation, with a value between 0 and 359, where 0 indicates a touch pointer aligned with the x-axis and pointing from left to right; increasing values indicate degrees of rotation in the clockwise direction. This field defaults to 0 if the device does not report orientation. > [!NOTE] > Some touchscreen devices that support orientation will only report half-range (0-180°) values, while other devices will only report full-range (0-359°) values. Read more on docs.microsoft.com.

Type: **UINT32** A pen pressure normalized to a range between 0 and 1024. The default is 512. Read more on docs.microsoft.com.

Specifies the FMTID/PID identifier that programmatically identifies a property. Replaces SHCOLUMNID.

As of Windows Vista, the SHCOLUMNID structure is simply an alias for PROPERTYKEY, as shown in this declaration from Shobjidl.h. This doc was truncated. Read more on docs.microsoft.com.

Type: GUID A unique GUID for the property. Read more on docs.microsoft.com.

Type: DWORD A property identifier (PID). This parameter is not used as in SHCOLUMNID. It is recommended that you set this value to PID_FIRST_USABLE. Any value greater than or equal to 2 is acceptable.

Note Values of 0 and 1 are reserved and should not be used.

Read more on docs.microsoft.com.

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 a file object. (Unicode)

This structure is used with the SHGetFileInfo function. > [!NOTE] > The shellapi.h header defines SHFILEINFO 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: HICON A handle to the icon that represents the file. You are responsible for destroying this handle with DestroyIcon when you no longer need it. Read more on docs.microsoft.com.

Type: int The index of the icon image within the system image list. Read more on docs.microsoft.com.

Type: DWORD An array of values that indicates the attributes of the file object. For information about these values, see the IShellFolder::GetAttributesOf method. Read more on docs.microsoft.com.

Type: TCHAR[MAX_PATH] A string that contains the name of the file as it appears in the Windows Shell, or the path and file name of the file that contains the icon representing the file. Read more on docs.microsoft.com.

Type: TCHAR[80] A string that describes the type of file. Read more on docs.microsoft.com.

Requests the form of an item's display name to retrieve through IShellItem::GetDisplayName and SHGetNameFromIDList.

Different forms of an item's name can be retrieved through the item's properties, including those listed here. Note that not all properties are present on all items, so only those appropriate to the item will appear. This doc was truncated. Read more on docs.microsoft.com.

0x00000000. Returns the display name relative to the parent folder. In UI this name is generally ideal for display to the user.

(int)0x80018001. Returns the parsing name relative to the parent folder. This name is not suitable for use in UI.

(int)0x80028000. Returns the parsing name relative to the desktop. This name is not suitable for use in UI.

(int)0x80031001. Returns the editing name relative to the parent folder. In UI this name is suitable for display to the user.

(int)0x8004c000. Returns the editing name relative to the desktop. In UI this name is suitable for display to the user.

(int)0x80058000. Returns the item's file system path, if it has one. Only items that report SFGAO_FILESYSTEM have a file system path. When an item does not have a file system path, a call to IShellItem::GetDisplayName on that item will fail. In UI this name is suitable for display to the user in some cases, but note that it might not be specified for all items.

(int)0x80068000. Returns the item's URL, if it has one. Some items do not have a URL, and in those cases a call to IShellItem::GetDisplayName will fail. This name is suitable for display to the user in some cases, but note that it might not be specified for all items.

(int)0x8007c001. Returns the path relative to the parent folder in a friendly format as displayed in an address bar. This name is suitable for display to the user.

(int)0x80080001. Returns the path relative to the parent folder.

(int)0x80094001. Introduced in Windows 8.

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 .

Contains extern methods from "COMCTL32.dll". Contains extern methods from "GDI32.dll". Contains extern methods from "KERNEL32.dll". Contains extern methods from "OLE32.dll". Contains extern methods from "SHELL32.dll". Contains extern methods from "urlmon.dll". Contains extern methods from "USER32.dll".

Destroys an image list.

Type: HIMAGELIST A handle to the image list to destroy. Read more on docs.microsoft.com. Type: BOOL Returns nonzero if successful, or zero otherwise. Learn more about this API from 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 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.

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 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.

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 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.

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.

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.

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.

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.

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.

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.

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.

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 a block of task memory previously allocated through a call to the CoTaskMemAlloc or CoTaskMemRealloc function.

A pointer to the memory block to be freed. If this parameter is NULL, the function has no effect. The CoTaskMemFree function uses the default OLE allocator. The number of bytes freed equals the number of bytes that were originally allocated or reallocated. After the call, the memory block pointed to by pv is invalid and can no longer be used. Read more on docs.microsoft.com.

Creates a stream object that uses an HGLOBAL memory handle to store the stream contents.

A memory handle allocated by the GlobalAlloc function, or if NULL a new handle is to be allocated instead. The handle must be allocated as moveable and nondiscardable. A value that indicates whether the underlying handle for this stream object should be automatically freed when the stream object is released. If set to FALSE, the caller must free the hGlobal after the final release. If set to TRUE, the final release will automatically free the underlying handle. See the Remarks for further discussion of the case where fDeleteOnRelease is FALSE. The address of IStream* pointer variable that receives the interface pointer to the new stream object. Its value cannot be NULL. Read more on docs.microsoft.com. This function supports the standard return values E_INVALIDARG and E_OUTOFMEMORY, as well as the following. If hGlobal is NULL, the function allocates a new memory handle and the stream is initially empty. If hGlobal is not NULL, the initial contents of the stream are the current contents of the memory block. Thus, CreateStreamOnHGlobal can be used to open an existing stream in memory. The memory handle and its contents are undisturbed by the creation of the new stream object. The initial size of the stream is the size of hGlobal as returned by the GlobalSize function. Because of rounding, this is not necessarily the same size that was originally allocated for the handle. If the logical size of the stream is important, follow the call to this function with a call to the IStream::SetSize method. The new stream object’s initial seek position is the beginning of the stream. After creating the stream object with CreateStreamOnHGlobal, call GetHGlobalFromStream to retrieve the memory handle associated with the stream object. If a memory handle is passed to CreateStreamOnHGlobal or if GetHGlobalFromStream is called, the memory handle of this function can be directly accessed by the caller while it is still in use by the stream object. Appropriate caution should be exercised in the use of this capability and its implications: 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.

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.

Creates a Shell item array object from a data object.

Type: IDataObject* A pointer to IDataObject interface. Read more on docs.microsoft.com. Type: REFIID A reference to the desired interface ID. Read more on docs.microsoft.com. Type: void** When this method returns, contains the interface pointer requested in riid. This is typically IShellItemArray. Read more on docs.microsoft.com. Type: HRESULT If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. This function is useful for Shell extensions that implement IShellExtInit and are passed a data object to the IShellExtInit::Initialize method; for example, context menu handlers. This API lets you convert the data object into a Shell item that the handler can consume. It is recommend that handlers use a Shell item array rather than clipboard formats like CF_HDROP and CFSTR_SHELLIDLIST (also known as HIDA) as it leads to simpler code and allows some performance improvements. The resulting shell item array holds a reference to the source data object. Therefore, that data object must remain valid for the lifetime of the shell item array. Notably, the data objects passed to IDropTarget methods are no longer valid after the drop operation completes. Read more on docs.microsoft.com.

SHCreateStdEnumFmtEtc may be altered or unavailable.

Type: UINT The number of entries in the afmt array. Read more on docs.microsoft.com. Type: const FORMATETC[] An array of FORMATETC structures that specifies the clipboard formats of interest. Read more on docs.microsoft.com. Type: IEnumFORMATETC** When this function returns successfully, receives an IEnumFORMATETC interface pointer. Receives NULL on failure. Read more on docs.microsoft.com. Type: HRESULT If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. Learn more about this API from docs.microsoft.com.

Retrieves information about an object in the file system, such as a file, folder, directory, or drive root. (Unicode)

Type: LPCTSTR A pointer to a null-terminated string of maximum length MAX_PATH that contains the path and file name. Both absolute and relative paths are valid. If the uFlags parameter includes the SHGFI_PIDL flag, this parameter must be the address of an ITEMIDLIST (PIDL) structure that contains the list of item identifiers that uniquely identifies the file within the Shell's namespace. The PIDL must be a fully qualified PIDL. Relative PIDLs are not allowed. If the uFlags parameter includes the SHGFI_USEFILEATTRIBUTES flag, this parameter does not have to be a valid file name. The function will proceed as if the file exists with the specified name and with the file attributes passed in the dwFileAttributes parameter. This allows you to obtain information about a file type by passing just the extension for pszPath and passing FILE_ATTRIBUTE_NORMAL in dwFileAttributes. This string can use either short (the 8.3 form) or long file names. Read more on docs.microsoft.com. Type: DWORD A combination of one or more file attribute flags (FILE_ATTRIBUTE_ values as defined in Winnt.h). If uFlags does not include the SHGFI_USEFILEATTRIBUTES flag, this parameter is ignored. Read more on docs.microsoft.com. Type: SHFILEINFO* Pointer to a SHFILEINFO structure to receive the file information. Read more on docs.microsoft.com. Type: UINT The size, in bytes, of the SHFILEINFO structure pointed to by the psfi parameter. Read more on docs.microsoft.com. Type: UINT Type: DWORD_PTR Returns a value whose meaning depends on the uFlags parameter. If uFlags does not contain SHGFI_EXETYPE or SHGFI_SYSICONINDEX, the return value is nonzero if successful, or zero otherwise. If uFlags contains the SHGFI_EXETYPE flag, the return value specifies the type of the executable file. It will be one of the following values. This doc was truncated. You should call this function from a background thread. Failure to do so could cause the UI to stop responding. If SHGetFileInfo returns an icon handle in the hIcon member of the SHFILEINFO structure pointed to by psfi, you are responsible for freeing it with DestroyIcon when you no longer need it.

Note Once you have a handle to a system image list, you can use the Image List API to manipulate it like any other image list. Because system image lists are created on a per-process basis, you should treat them as read-only objects. Writing to a system image list may overwrite or delete one of the system images, making it unavailable or incorrect for the remainder of the process.

You must initialize Component Object Model (COM) with CoInitialize or OleInitialize prior to calling SHGetFileInfo. When you use the SHGFI_EXETYPE flag with a Windows application, the Windows version of the executable is given in the HIWORD of the return value. This version is returned as a hexadecimal value. For details on equating this value with a specific Windows version, see Using the Windows Headers. Read more on docs.microsoft.com.

Retrieves an image list.

Type: int Type: REFIID Reference to the image list interface identifier, normally IID_IImageList. Read more on docs.microsoft.com. Type: void** When this method returns, contains the interface pointer requested in riid. This is typically IImageList. Read more on docs.microsoft.com. Type: HRESULT If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. The IImageList pointer type, such as that returned in the ppv parameter, can be cast as an HIMAGELIST as needed; for example, for use in a list view. Conversely, an HIMAGELIST can be cast as a pointer to an IImageList. As of Windows Vista, SHIL_SMALL, SHIL_LARGE, and SHIL_EXTRALARGE scale with dots per inch (dpi) if the process is marked as dpi-aware. To set these types to be dpi-aware, call SetProcessDPIAware. SHIL_JUMBO is fixed at 256 pixels regardless of the dpi-aware setting. Read more on docs.microsoft.com.

Retrieves the status of the specified virtual key. The status specifies whether the key is up, down, or toggled (on, off�alternating each time the key is pressed).

Type: int A virtual key. If the desired virtual key is a letter or digit (A through Z, a through z, or 0 through 9), nVirtKey must be set to the ASCII value of that character. For other keys, it must be a virtual-key code. If a non-English keyboard layout is used, virtual keys with values in the range ASCII A through Z and 0 through 9 are used to specify most of the character keys. For example, for the German keyboard layout, the virtual key of value ASCII O (0x4F) refers to the "o" key, whereas VK_OEM_1 refers to the "o with umlaut" key. Read more on docs.microsoft.com. Type: SHORT The return value specifies the status of the specified virtual key, as follows: This doc was truncated. The key status returned from this function changes as a thread reads key messages from its message queue. The status does not reflect the interrupt-level state associated with the hardware. Use the GetAsyncKeyState function to retrieve that information. An application calls GetKeyState in response to a keyboard-input message. This function retrieves the state of the key when the input message was generated. To retrieve state information for all the virtual keys, use the GetKeyboardState function. An application can use the virtual key code constants VK_SHIFT, VK_CONTROL, and VK_MENU as values for the nVirtKey parameter. This gives the status of the SHIFT, CTRL, or ALT keys without distinguishing between left and right. An application can also use the following virtual-key code constants as values for nVirtKey to distinguish between the left and right instances of those keys: VK_LSHIFT VK_RSHIFT VK_LCONTROL VK_RCONTROL VK_LMENU VK_RMENU These left- and right-distinguishing constants are available to an application only through the GetKeyboardState, SetKeyboardState, GetAsyncKeyState, GetKeyState, and MapVirtualKey functions. Read more on docs.microsoft.com.

Retrieves the pointer type for a specified pointer.

An identifier of the pointer for which to retrieve pointer type. An address of a POINTER_INPUT_TYPE type to receive a pointer input type. If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. To get extended error information, call GetLastError. An application can use the GetPointerType function to determine the pointer type if it wishes to react differently to pointers of different types.

Note This function will never return with the generic PT_POINTER type.

Read more on docs.microsoft.com.

Gets the information for the specified pointer associated with the current message.

The pointer identifier. Address of a POINTER_INFO structure that receives the pointer information. If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. To get extended error information, call GetLastError. GetPointerInfo retrieves information for a single pointer associated with a pointer message. Use GetPointerFrameInfo to retrieve frame information associated with a message for a set of pointers. The information returned by GetPointerInfo is associated with the most recent pointer message retrieved by the calling thread. When the next message is retrieved by the calling thread, the information associated with the previous message may no longer be available. If the application does not process pointer input messages as fast as they are generated, some messages may be coalesced into a WM_POINTERUPDATE message. Use GetPointerInfoHistory to retrieve the message history from the most recent WM_POINTERUPDATE message. If the information associated with the message is no longer available, this function fails with the last error set to ERROR_NO_DATA. If the calling thread does not own the window to which the pointer message has been delivered, this function fails with the last error set to ERROR_ACCESS_DENIED. Note that this may be the window to which the input was originally delivered or it may be a window to which the message was forwarded. Read more on docs.microsoft.com.

Gets the touch-based information for the specified pointer (of type PT_TOUCH) associated with the current message.

An identifier of the pointer for which to retrieve information. Address of a POINTER_TOUCH_INFO structure to receive the touch-specific pointer information. If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. To get extended error information, call GetLastError. GetPointerTouchInfo retrieves information for a single pointer (of type PT_TOUCH) associated with a pointer message. Use GetPointerFrameTouchInfo to retrieve frame information associated with a message for a set of pointers. The information returned by GetPointerTouchInfo is associated with the most recent pointer message retrieved by the calling thread. When the next message is retrieved by the calling thread, the information associated with the previous message may no longer be available. If the application does not process pointer input messages as fast as they are generated, some messages may be coalesced into a WM_POINTERUPDATE message. Use GetPointerTouchInfoHistory to retrieve the message history from the most recent WM_POINTERUPDATE message. If the information associated with the message is no longer available, this function fails with the last error set to ERROR_NO_DATA. If the calling thread does not own the window to which the pointer message has been delivered, this function fails with the last error set to ERROR_ACCESS_DENIED. Note that this may be the window to which the input was originally delivered or it may be a window to which the message was forwarded. If the specified pointer is not of type PT_TOUCH, this function fails with the last error set to ERROR_DATATYPE_MISMATCH. Read more on docs.microsoft.com.

Gets the pen-based information for the specified pointer (of type PT_PEN) associated with the current message.

An identifier of the pointer for which to retrieve information. Address of a POINTER_PEN_INFO structure to receive the pen-specific pointer information. If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. To get extended error information, call GetLastError. GetPointerPenInfo retrieves information for a single pointer (of type PT_PEN) associated with a pointer message. Use GetPointerFramePenInfo to retrieve frame information associated with a message for a set of pointers. The information returned by GetPointerInfo is associated with the most recent pointer message retrieved by the calling thread. When the next message is retrieved by the calling thread, the information associated with the previous message may no longer be available. If the application does not process pointer input messages as fast as they are generated, some messages may be coalesced into a WM_POINTERUPDATE message. Use GetPointerPenInfoHistory to retrieve the message history from the most recent WM_POINTERUPDATE message. If the information associated with the message is no longer available, this function fails with the last error set to ERROR_NO_DATA. If the calling thread does not own the window to which the pointer message has been delivered, this function fails with the last error set to ERROR_ACCESS_DENIED. Note that this may be the window to which the input was originally delivered or it may be a window to which the message was forwarded. If the specified pointer is not of type PT_PEN, this function fails with the last error set to ERROR_DATATYPE_MISMATCH. Read more on docs.microsoft.com.

Removes a hook procedure installed in a hook chain by the SetWindowsHookEx function.

Type: HHOOK A handle to the hook to be removed. This parameter is a hook handle obtained by a previous call to SetWindowsHookEx. 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 hook procedure can be in the state of being called by another thread even after UnhookWindowsHookEx returns. If the hook procedure is not being called concurrently, the hook procedure is removed immediately before UnhookWindowsHookEx returns.

Installs an application-defined hook procedure into a hook chain. (Unicode)

Type: int Type: HOOKPROC A pointer to the hook procedure. If the dwThreadId parameter is zero or specifies the identifier of a thread created by a different process, the lpfn parameter must point to a hook procedure in a DLL. Otherwise, lpfn can point to a hook procedure in the code associated with the current process. Read more on docs.microsoft.com. Type: HINSTANCE A handle to the DLL containing the hook procedure pointed to by the lpfn parameter. The hMod parameter must be set to NULL if the dwThreadId parameter specifies a thread created by the current process and if the hook procedure is within the code associated with the current process. Read more on docs.microsoft.com. Type: DWORD The identifier of the thread with which the hook procedure is to be associated. For desktop apps, if this parameter is zero, the hook procedure is associated with all existing threads running in the same desktop as the calling thread. For Windows Store apps, see the Remarks section. Read more on docs.microsoft.com. Type: HHOOK If the function succeeds, the return value is the handle to the hook procedure. If the function fails, the return value is NULL. To get extended error information, call GetLastError. SetWindowsHookEx can be used to inject a DLL into another process. A 32-bit DLL cannot be injected into a 64-bit process, and a 64-bit DLL cannot be injected into a 32-bit process. If an application requires the use of hooks in other processes, it is required that a 32-bit application call SetWindowsHookEx to inject a 32-bit DLL into 32-bit processes, and a 64-bit application call SetWindowsHookEx to inject a 64-bit DLL into 64-bit processes. The 32-bit and 64-bit DLLs must have different names. Because hooks run in the context of an application, they must match the "bitness" of the application. If a 32-bit application installs a global hook on 64-bit Windows, the 32-bit hook is injected into each 32-bit process (the usual security boundaries apply). In a 64-bit process, the threads are still marked as "hooked." However, because a 32-bit application must run the hook code, the system executes the hook in the hooking app's context; specifically, on the thread that called SetWindowsHookEx. This means that the hooking application must continue to pump messages or it might block the normal functioning of the 64-bit processes. If a 64-bit application installs a global hook on 64-bit Windows, the 64-bit hook is injected into each 64-bit process, while all 32-bit processes use a callback to the hooking application. To hook all applications on the desktop of a 64-bit Windows installation, install a 32-bit global hook and a 64-bit global hook, each from appropriate processes, and be sure to keep pumping messages in the hooking application to avoid blocking normal functioning. If you already have a 32-bit global hooking application and it doesn't need to run in each application's context, you may not need to create a 64-bit version. An error may occur if the hMod parameter is NULL and the dwThreadId parameter is zero or specifies the identifier of a thread created by another process. Calling the CallNextHookEx function to chain to the next hook procedure is optional, but it is highly recommended; otherwise, other applications that have installed hooks will not receive hook notifications and may behave incorrectly as a result. You should call CallNextHookEx unless you absolutely need to prevent the notification from being seen by other applications. Before terminating, an application must call the UnhookWindowsHookEx function to free system resources associated with the hook. The scope of a hook depends on the hook type. Some hooks can be set only with global scope; others can also be set for only a specific thread, as shown in the following table. This doc was truncated. Read more on docs.microsoft.com.

Passes the hook information to the next hook procedure in the current hook chain. A hook procedure can call this function either before or after processing the hook information.

Type: HHOOK This parameter is ignored. Read more on docs.microsoft.com. Type: int The hook code passed to the current hook procedure. The next hook procedure uses this code to determine how to process the hook information. Read more on docs.microsoft.com. Type: WPARAM The wParam value passed to the current hook procedure. The meaning of this parameter depends on the type of hook associated with the current hook chain. Read more on docs.microsoft.com. Type: LPARAM The lParam value passed to the current hook procedure. The meaning of this parameter depends on the type of hook associated with the current hook chain. Read more on docs.microsoft.com. Type: LRESULT This value is returned by the next hook procedure in the chain. The current hook procedure must also return this value. The meaning of the return value depends on the hook type. For more information, see the descriptions of the individual hook procedures. Hook procedures are installed in chains for particular hook types. CallNextHookEx calls the next hook in the chain. Calling CallNextHookEx is optional, but it is highly recommended; otherwise, other applications that have installed hooks will not receive hook notifications and may behave incorrectly as a result. You should call CallNextHookEx unless you absolutely need to prevent the notification from being seen by other 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.

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 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.

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.

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.

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.

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.

Retrieves the position of the mouse cursor, in screen coordinates.

Type: LPPOINT A pointer to a POINT structure that receives the screen coordinates of the cursor. Read more on docs.microsoft.com. Type: BOOL Returns nonzero if successful or zero otherwise. To get extended error information, call GetLastError. The cursor position is always specified in screen coordinates and is not affected by the mapping mode of the window that contains the cursor. The calling process must have WINSTA_READATTRIBUTES access to the window station. The input desktop must be the current desktop when you call GetCursorPos. Call OpenInputDesktop to determine whether the current desktop is the input desktop. If it is not, call SetThreadDesktop with the HDESK returned by OpenInputDesktop to switch to that desktop. Read more on docs.microsoft.com.

Moves the cursor to the specified screen coordinates.

Type: int The new x-coordinate of the cursor, in screen coordinates. Read more on docs.microsoft.com. Type: int The new y-coordinate of the cursor, in screen coordinates. Read more on docs.microsoft.com. Type: BOOL Returns nonzero if successful or zero otherwise. To get extended error information, call GetLastError. The cursor is a shared resource. A window should move the cursor only when the cursor is in the window's client area. The calling process must have WINSTA_WRITEATTRIBUTES access to the window station. The input desktop must be the current desktop when you call SetCursorPos. Call OpenInputDesktop to determine whether the current desktop is the input desktop. If it is not, call SetThreadDesktop with the HDESK returned by OpenInputDesktop to switch to that desktop. Read more on docs.microsoft.com.

Represents a Win32 handle that can be closed with .