com topic

COM-based APIs

Windows APIs that use the COM invocation model.

Since the Win32 package primarily focuses on providing a lightweight wrapper for the underlying Windows API primitives, you can use the same API calls as described in Microsoft documentation to create an manipulate objects (e.g. CoCreateInstance and IUnknown->QueryInterface). However, since this introduces a certain amount of boilerplate and non-idiomatic Dart code, the library also provides some helper functions that reduce the labor compared to a pure C-style calling convention.

Initializing the COM library

Before you call any COM functions, first initialize the COM library by calling the CoInitializeEx function. Details of the threading models are outside the scope of this document, but typically you should write something like:

final hr = CoInitializeEx(
    nullptr, COINIT_APARTMENTTHREADED | COINIT_DISABLE_OLE1DDE);
if (FAILED(hr)) throw WindowsException(hr);

Creating a COM object

You can create COM objects using the C library:

hr = CoCreateInstance(clsid, nullptr, CLSCTX_INPROC_SERVER, iid, ppv);

However, rather than manually allocate GUID structs for the clsid and iid values, checking the hr result code and deal with casting the ppv return object, it is easier to use the createFromID static helper function:

final fileDialog2 = IFileDialog2(
  COMObject.createFromID(CLSID_FileOpenDialog, IID_IFileDialog2));

createFromID returns a Pointer<COMObject> containing the requested object, which can then be cast into the appropriate interface as shown above. It is the caller's responsibility to free the returned pointer when all interfaces that derive from it are released.

Asking a COM object for an interface

COM allows objects to implement multiple interfaces, but it does not let you merely cast an object to a different interface. Instead, returned pointers are to a specific interface. However, every COM interface in the Dart Win32 package derives from IUnknown, so as in other language implementations of COM, you may call queryInterface on any object to retrieve a pointer to a different supported interface.

More information on COM interfaces may be found in the Microsoft documentation.

COM interfaces supply a method that wraps queryInterface. If you have an existing COM object, you can call it as follows:

  final modalWindow = IModalWindow.from(fileDialog2);

Where createFromID creates a new COM object, toInterface casts an existing COM object to a new interface. As with createFromID, it is the caller's responsibility to free the returned pointer when all interfaces that derive from it are released.

Attempting to cast a COM object to an interface it does not support will fail, of course. A WindowsException will be thrown with an hr of E_NOINTERFACE.

Calling a method on a COM object

No special considerations are needed here; however, it is wise to assign the return value to a variable and test it for success or failure. You can use the SUCCEEDED() or FAILED() top-level functions to do this, for example:

final hr = fileOpenDialog.show(NULL);
if (SUCCEEDED(hr)) {
  // Do something with the returned dialog box values
}

Failures are reported as HRESULT values (e.g. E_ACCESSDENIED). Sometimes a Win32 error code is converted to an HRESULT, as in the case where a user cancels a common dialog box:

final hr = fileOpenDialog.show(NULL);
if (FAILED(hr) && hr == HRESULT_FROM_WIN32(ERROR_CANCELLED)) {
  // User clicked cancel
}

Releasing COM objects

When you have finished using a COM interface, you should release it with the release method:

fileOpenDialog.release(); // Release the interface
free(fileOpenDialog.ptr); // Release the pointer to the interface

Often this will be called as part of a try / finally block, to guarantee that the object is released even if an exception is thrown.

Unloading COM support

When you have finished using COM, you should uninitialize it with the following call:

CoUninitialize();

A full example of these calls can be found in the com_demo.dart file in the example\ subfolder.

Classes

ApplicationActivationManager com
AppxFactory com
COMObject com Interface
A representation of a generic COM object. All Dart COM objects inherit from this class.
DesktopWallpaper com
FileOpenDialog com
FileSaveDialog com
IApplicationActivationManager com Interface
IAppxFactory com Interface
IAppxFile com Interface
Retrieves information about a payload or footprint file in a package.
IAppxFilesEnumerator com Interface
Enumerates the payload files in a package.
IAppxManifestApplication com Interface
Provides access to attribute values of the application.
IAppxManifestApplicationsEnumerator com Interface
Enumerates the applications defined in the package manifest.
IAppxManifestOSPackageDependency com Interface
IAppxManifestPackageDependenciesEnumerator com Interface
Enumerates the package dependencies defined in the package manifest.
IAppxManifestPackageDependency com Interface
Describes the dependency of one package on another package.
IAppxManifestPackageId com Interface
Provides access to the package identity.
IAppxManifestProperties com Interface
Provides read-only access to the properties section of a package manifest.
IAppxManifestReader com Interface
Represents an object model of the package manifest that provides methods to access manifest elements and attributes.
IAppxManifestReader2 com Interface
Represents an object model of the package manifest that provides methods to access manifest elements and attributes.
IAppxManifestReader3 com Interface
Represents an object model of the package manifest that provides methods to access manifest elements and attributes.
IAppxManifestReader4 com Interface
Represents an object model of the package manifest that provides methods to access manifest elements and attributes.
IAppxManifestReader5 com Interface
Represents an object model of the package manifest that provides methods to access manifest elements and attributes.
IAppxManifestReader6 com Interface
Represents an object model of the package manifest that provides methods to access manifest elements and attributes.
IAppxManifestReader7 com Interface
Represents an object model of the package manifest that provides methods to access manifest elements and attributes.
IAppxPackageReader com Interface
Provides a read-only object model for app packages.
IAudioCaptureClient com Interface
The IAudioCaptureClient interface enables a client to read input data from a capture endpoint buffer. The client obtains a reference to the IAudioCaptureClient interface on a stream object by calling the IAudioClient::GetService method with parameter riid set to REFIID IID_IAudioCaptureClient.
IAudioClient com Interface
The IAudioClient interface enables a client to create and initialize an audio stream between an audio application and the audio engine (for a shared-mode stream) or the hardware buffer of an audio endpoint device (for an exclusive-mode stream).
IAudioClock com Interface
The IAudioClock interface enables a client to monitor a stream's data rate and the current position in the stream. The client obtains a reference to the IAudioClock interface of a stream object by calling the IAudioClient::GetService method with parameter riid set to REFIID IID_IAudioClock.
IAudioRenderClient com Interface
The IAudioRenderClient interface enables a client to write output data to a rendering endpoint buffer. The client obtains a reference to the IAudioRenderClient interface of a stream object by calling the IAudioClient::GetService method with parameter riid set to REFIID IID_IAudioRenderClient.
IAudioSessionControl com Interface
The IAudioSessionControl interface enables a client to configure the control parameters for an audio session and to monitor events in the session. The IAudioClient::Initialize method initializes a stream object and assigns the stream to an audio session. The client obtains a reference to the IAudioSessionControl interface on a stream object by calling the IAudioClient::GetService method with parameter riid set to REFIID IID_IAudioSessionControl.
IAudioSessionManager com Interface
The IAudioSessionManager interface enables a client to access the session controls and volume controls for both cross-process and process-specific audio sessions. The client obtains a reference to an IAudioSessionManager interface by calling the IMMDevice::Activate method with parameter iid set to REFIID IID_IAudioSessionManager.
IAudioStreamVolume com Interface
The IAudioStreamVolume interface enables a client to control and monitor the volume levels for all of the channels in an audio stream. The client obtains a reference to the IAudioStreamVolume interface on a stream object by calling the IAudioClient::GetService method with parameter riid set to REFIID IID_IAudioStreamVolume.
IBindCtx com Interface
Provides access to a bind context, which is an object that stores information about a particular moniker binding operation.
IChannelAudioVolume com Interface
The IChannelAudioVolume interface enables a client to control and monitor the volume levels for all of the channels in the audio session that the stream belongs to. This is the session that the client assigned the stream to during the call to the IAudioClient::Initialize method. The client obtains a reference to the IChannelAudioVolume interface on a stream object by calling the IAudioClient::GetService method with parameter riid set to REFIID IID_IChannelAudioVolume.
IClassFactory com Interface
Creates a call object for processing calls to the methods of an asynchronous interface.
IConnectionPoint com Interface
Supports connection points for connectable objects.
IConnectionPointContainer com Interface
Supports connection points for connectable objects.
IDesktopWallpaper com Interface
IDispatch com Interface
Exposes objects, methods and properties to programming tools and other applications that support Automation.
IEnumIDList com Interface
Exposes a standard set of methods used to enumerate the pointers to item identifier lists (PIDLs) of the items in a Shell folder. When a folder's IShellFolder::EnumObjects method is called, it creates an enumeration object and passes a pointer to the object's IEnumIDList interface back to the calling application.
IEnumMoniker com Interface
Enumerates the components of a moniker or the monikers in a table of monikers.
IEnumNetworkConnections com Interface
The IEnumNetworkConnections interface provides a standard enumerator for network connections. It enumerates active, disconnected, or all network connections within a network. This interface can be obtained from the INetwork interface.
IEnumNetworks com Interface
The IEnumNetworks interface is a standard enumerator for networks. It enumerates all networks available on the local machine. This interface can be obtained from the INetworkListManager interface.
IEnumResources com Interface
Exposes resource enumeration methods.
IEnumSpellingError com Interface
An enumeration of the spelling errors.
IEnumString com Interface
Enumerate strings. LPWSTR is the type that indicates a pointer to a zero-terminated string of wide, or Unicode, characters.
IEnumVARIANT com Interface
Provides a method for enumerating a collection of variants, including heterogeneous collections of objects and intrinsic types. Callers of this interface do not need to know the specific type (or types) of the elements in the collection.
IEnumWbemClassObject com Interface
The IEnumWbemClassObject interface is used to enumerate Common Information Model (CIM) objects and is similar to a standard COM enumerator.
IErrorInfo com Interface
IErrorInfo is defined by Automation; the following describes how the interface is used in OLE DB. IErrorInfo returns information about an error in addition to the return code. It returns the error message, name of the component and GUID of the interface in which the error occurred, and the name and topic of the Help file that applies to the error.
IFileDialog com Interface
Exposes methods that initialize, show, and get results from the common file dialog.
IFileDialog2 com Interface
Extends the IFileDialog interface by providing methods that allow the caller to name a specific, restricted location that can be browsed in the common file dialog as well as to specify alternate text to display as a label on the Cancel button.
IFileDialogCustomize com Interface
Exposes methods that allow an application to add controls to a common file dialog.
IFileIsInUse com Interface
Exposes methods that can be called to get information on or close a file that is in use by another application. When an application attempts to access a file and finds that file already in use, it can use the methods of this interface to gather information to present to the user in a dialog box.
IFileOpenDialog com Interface
IFileSaveDialog com Interface
IInspectable com Interface
Provides functionality required for all Windows Runtime classes.
IKnownFolder com Interface
Exposes methods that allow an application to retrieve information about a known folder's category, type, GUID, pointer to an item identifier list (PIDL) value, redirection capabilities, and definition. It provides a method for the retrieval of a known folder's IShellItem object. It also provides methods to get or set the path of the known folder.
IKnownFolderManager com Interface
IMMDevice com Interface
The IMMDevice interface encapsulates the generic features of a multimedia device resource.
IMMDeviceEnumerator com Interface
IModalWindow com Interface
Exposes a method that represents a modal window.
IMoniker com Interface
Enables you to use a moniker object, which contains information that uniquely identifies a COM object. An object that has a pointer to the moniker object's IMoniker interface can locate, activate, and get access to the identified object without having any other specific information on where the object is actually located in a distributed system. Monikers are used as the basis for linking in COM. A linked object contains a moniker that identifies its source. When the user activates the linked object to edit it, the moniker is bound; this loads the link source into memory.
INetwork com Interface
The INetwork interface represents a network on the local machine. It can also represent a collection of network connections with a similar network signature.
INetworkConnection com Interface
The INetworkConnection interface represents a single network connection.
INetworkListManager com Interface
INetworkListManagerEvents com Interface
INetworkListManagerEvents is a message sink interface that a client implements to get overall machine state related events. Applications that are interested on higher-level events, for example internet connectivity, implement this interface.
IPersist com Interface
Provides the CLSID of an object that can be stored persistently in the system. Allows the object to specify which object handler to use in the client process, as it is used in the default implementation of marshaling.
IPersistFile com Interface
Enables an object to be loaded from or saved to a disk file, rather than a storage object or stream. Because the information needed to open a file varies greatly from one application to another, the implementation of IPersistFile::Loadon the object must also open its disk file.
IPersistMemory com Interface
Saves and loads objects from a stream.
IPersistStream com Interface
Enables the saving and loading of objects that use a simple serial stream for their storage needs.
IProvideClassInfo com Interface
Provides access to the type information for an object's coclass entry in its type library.
IRunningObjectTable com Interface
Manages access to the running object table (ROT), a globally accessible look-up table on each workstation. A workstation's ROT keeps track of those objects that can be identified by a moniker and that are currently running on the workstation. When a client tries to bind a moniker to an object, the moniker checks the ROT to see if the object is already running; this allows the moniker to bind to the current instance instead of loading a new one.
ISensor com Interface
ISensorCollection com Interface
ISensorDataReport com Interface
ISensorManager com Interface
ISequentialStream com Interface
The ISequentialStream interface supports simplified sequential access to stream objects. The IStream interface inherits its Read and Write methods from ISequentialStream.
IShellFolder com Interface
Exposed by all Shell namespace folder objects, its methods are used to manage folders.
IShellItem com Interface
IShellItem2 com Interface
Extends IShellItem with methods that retrieve various property values of the item. IShellItem and IShellItem2 are the preferred representations of items in any new code.
IShellItemArray com Interface
Exposes methods that create and manipulate Shell item arrays.
IShellItemFilter com Interface
Exposed by a client to specify how to filter the enumeration of a Shell item by a server application.
IShellItemImageFactory com Interface
Exposes a method to return either icons or thumbnails for Shell items. If no thumbnail or icon is available for the requested item, a per-class icon may be provided from the Shell.
IShellItemResources com Interface
Exposes methods to manipulate and query Shell item resources.
IShellLinkDataList com Interface
Exposes methods that allow an application to attach extra data blocks to a Shell link. These methods add, copy, or remove data blocks.
IShellLinkDual com Interface
IShellService com Interface
IShellService Exposes one method that declares ownership when a service component implementing a certain interface is shared among multiple clients, such as Windows Internet Explorer and Windows Explorer.
ISimpleAudioVolume com Interface
The ISimpleAudioVolume interface enables a client to control the master volume level of an audio session. The IAudioClient::Initialize method initializes a stream object and assigns the stream to an audio session. The client obtains a reference to the ISimpleAudioVolume interface on a stream object by calling the IAudioClient::GetService method with parameter riid set to REFIID IID_ISimpleAudioVolume.
ISpeechObjectToken com Interface
ISpeechObjectTokens com Interface
The ISpeechObjectTokens automation interface represents a collection of SpObjectToken objects.
ISpellChecker com Interface
Represents a particular spell checker for a particular language. The ISpellChecker can be used to check text, get suggestions, update user dictionaries, and maintain options.
ISpellChecker2 com Interface
Represents a particular spell checker for a particular language, with the added ability to remove words from the added words dictionary, or from the ignore list. The ISpellChecker2 can also be used to check text, get suggestions, update user dictionaries, and maintain options, as can ISpellChecker from which it is derived.
ISpellCheckerChangedEventHandler com Interface
Allows the caller to create a handler for notifications that the state of the speller has changed.
ISpellCheckerFactory com Interface
ISpellingError com Interface
Provides information about a spelling error.
ISpEventSource com Interface
Using the methods on ISpNotifySource an application can specify the mechanism by which it receives notifications. Applications can configure which events should trigger notifications and which events retrieve queued events. ISpEventSource inherits from the ISpNotifySource interface.
ISpNotifySource com Interface
In both speech synthesis and speech recognition, applications receive notifications when words have been spoken or when phrases have been recognized. SAPI components that generate notifications implement an ISpNotifySource.
ISpVoice com Interface
IStream com Interface
The IStream interface lets you read and write data to stream objects. Stream objects contain the data in a structured storage object, where storages provide the structure. Simple data can be written directly to a stream but, most frequently, streams are elements nested within a storage object. They are similar to standard files.
ISupportErrorInfo com Interface
Ensures that error information can be propagated up the call chain correctly. Automation objects that use the error handling interfaces must implement ISupportErrorInfo.
ITypeInfo com Interface
This section describes ITypeInfo, an interface typically used for reading information about objects. For example, an object browser tool can use ITypeInfo to extract information about the characteristics and capabilities of objects from type libraries.
IUnknown com Interface
Enables clients to get pointers to other interfaces on a given object through the QueryInterface method, and manage the existence of the object through the AddRef and Release methods. All other COM interfaces are inherited, directly or indirectly, from IUnknown. Therefore, the three methods in IUnknown are the first entries in the vtable for every interface.
IUri com Interface
Exposes methods and properties used to parse and build Uniform Resource Identifiers (URIs).
IVirtualDesktopManager com Interface
IWbemClassObject com Interface
IWbemConfigureRefresher com Interface
The IWbemConfigureRefresher interface is used by client code to add enumerators, objects, and nested refreshers into a refresher.
IWbemContext com Interface
IWbemHiPerfEnum com Interface
The IWbemHiPerfEnum interface is used in refresher operations to provide rapid access to enumerations of instance objects. WMI provides an implementation of this interface, which it passes to providers when IWbemHiPerfProvider::CreateRefreshableEnum is called, and it returns to clients when IWbemConfigureRefresher::AddEnum is called.
IWbemLocator com Interface
IWbemObjectAccess com Interface
The IWbemObjectAccess interface provides access to the methods and properties of an object. An IWbemObjectAccess object is a container for an instance updated by a refresher. With the IWbemObjectAccess interface, you can get and set properties by using property handles instead of object property names.
IWbemRefresher com Interface
IWbemServices com Interface
The IWbemServices interface is used by clients and providers to access WMI services. The interface is implemented by WMI and WMI providers, and is the primary WMI interface.
KnownFolderManager com
MMDeviceEnumerator com
NetworkListManager com
Sensor com
SensorCollection com
SensorDataReport com
SensorManager com
ShellItem com
SpellCheckerFactory com
SpVoice com
VirtualDesktopManager com
WbemClassObject com
WbemContext com
WbemLocator com
WbemRefresher com

Functions

convertToCLSID(String strCLSID, {Allocator allocator = calloc}) → Pointer<GUID> com
Converts a Dart string into an CLSID using the CLSIDFromString call.
convertToIID(String strIID, {Allocator allocator = calloc}) → Pointer<GUID> com
Converts a Dart string into an IID using the IIDFromString call.