Purpose of All OLE APIs and Interfaces

• Microsoft OLE

SUMMARY

OLE is a set of implemented services, mechanisms to customize these services, and mechanisms to install custom services according to various protocols. Every OLE API function and every currently-defined interface (that is, those found in shipping OLE technologies) have a purpose in this framework. Listed below are API functions and interfaces along with their purposes, categorized in the following functional groups:

• General
• Initialization and Memory Management
• Remoting
• Custom Services
• Service Registration
• DLL Server Management
• Miscellaneous COM Functions
• Naming (Monikers)
• Structured Storage
• Persistent Objects
• Notifications/Events
• Uniform Data Transfer
• Viewable Objects
• Standard Types
• OLE Clipboard
• OLE Drag & Drop
• Type Libraries
• OLE Automation
• OLE Property Pages
• OLE Documents: General
• OLE Documents: Handlers and Caching
• OLE Documents: Embedding
• OLE Documents: Linking
• OLE Documents: In-Place Activation
• OLE Documents: OLE 1 Compatibility
• OLE Controls

MORE INFORMATION

The following list helps illustrate why the various APIs and interfaces exist and includes the following information:

   Functions: <List of OLE API Functions and Interfaces>
     Purpose: <Purpose Description>

GENERAL

Functions: IUnknown

  Purpose: Control of object lifetime, interface negotiation. Ubiquitous
           for any component regardless of implementation. QueryInterface
           exposes incoming interfaces.

  Purpose: Enumeration of various types of lists. Used in many cases
           throughout OLE.

  Purpose: Expose the type information about an object's incoming and
           outgoing interfaces.

           IConnectionPoint, IEnumConnections
  Purpose: Expose an object's outgoing interfaces.

Initialization and Memory Management

Functions: CoBuildVersion, OleBuildVersion

  Purpose: Check OLE library version numbers.

  Purpose: Task memory allocation.

  Purpose: Initialize/Uninitialize COM/OLE libraries and installs an OLE-
           provided task allocator (most OLE implementations also allow
           installation of a custom allocator).

  Purpose: Access standard task memory allocator.

  Purpose: Access currently installed task allocator.

Remoting

Functions: IExternalConnection

  Purpose: Notification - connection/disconnection from remote process.

  Purpose: Lock a remote object implementation.

  Purpose: Forcibly disconnect any remote connections.

  Purpose: Standard marshaling (OLE impl); custom marshaling (custom impl).

  Purpose: Access standard implementation of IMarshal.

  Purpose: Support for Custom Interfaces.

           CoUnmarshalInterface, CoReleaseMarshalData
  Purpose: Helpers for marshaling both standard and custom.
           CoMarshalInterface, for example, is always called whenever any
           object needs to create the server-side remoting support for an
           interface pointer to a new object. CoUnmarshalInterface creates
           the client side to match.

  Purpose: Helper to determine if an in-process component is connected to a
           remote process.

  Purpose: Installs a custom IMessageFilter implementation.

  Purpose: Helper functions for OLE 1 container document compatibility.

  Purpose: Concurrency management handling interface. A default
           implementation is always installed when remoting occurs.

Custom Services

Functions: CoCreateInstance

  Purpose: Access custom component implementation given a CLSID.

  Purpose: Creation of custom component based on CLSID.

  Purpose: Access custom class factory implementation given a CLSID.

  Purpose: Expose a custom class factory implementation from a DLL.

  Purpose: Install/remove a custom class factory implementation.

Service Registration

Functions: CoCreateGuid, IsEqualGUID, IsEqualIID, IsEqualCLSID

  Purpose: Helper for creation and comparison of GUIDs.

  Purpose: Expose self-registration functionality from a DLL server module.

           OleGetAutoConvert, OleSetAutoConvert, GetConvertStg,
           SetConvertStg
  Purpose: Conversion/Emulation manipulation (only customization is
           registry information that describes which classes are
           interchangeable).

DLL Server Management

Functions: DllCanUnloadNow

  Purpose: Control DLL server unloading.

           CoFreeUnusedLibraries
  Purpose: Load and unload in-process server modules.

Miscellaneous COM Functions

Functions: CLSIDFrom[ProgID | String], [ProgID | String]FromCLSID,

           IIDFromString, StringFromIID, StringFromGUID2
  Purpose: Helper functions for conversion between GUIDs, strings, and
           ProgIDs.

  Purpose: Miscellaneous helper.

  Purpose: Miscellaneous helper functions for date/time conversion. (More
           appropriate to be a Win32 API).

  Purpose: Miscellaneous validation functions (16-bit only).

Naming (Monikers)

Functions: IMoniker

  Purpose: Exposes moniker functionality. OLE provides five moniker
           implementations (five different classes). Custom implementations
           can be exposed via object creation functions or custom API.

  Purpose: Wrapper for IMoniker::BindToObject.

           CreatePointerMoniker, CreateGenericComposite
  Purpose: Access OLE standard moniker implementations.

  Purpose: Implemented on a custom object to parse a user-readable display
           name into a moniker object, standard or custom.

  Purpose: While generally related to OLE Documents, these interfaces are
           implemented on an object that contains items and is necessary to
           bind item monikers.

  Purpose: Implemented on the OLE standard "bind context" object.

  Purpose: Instantiates a bind context object returning an IBindCtx
           pointer.

  Purpose: Exposed from the OLE implemented "running object table" service.
           No customizations.

  Purpose: Access the running object table.

  Purpose: Converts a string into a moniker which includes the intelligence
           to determine whose implementation of IParseDisplayName to use.

  Purpose: Helpers to manipulate file monikers to create absolute and
           relative paths using IMoniker::RelativePathTo and
           IMoniker::CommonPrefixWith.

Structured Storage

Functions: IStorage

  Purpose: Expose storage object functionality (directory).

  Purpose: Expose stream object functionality (files).

  Purpose: Control underlying file attached to an IStorage in a Compound
           File.

  Purpose: Customize underlying storage medium in a Compound File.

  Purpose: Create or open OLE's Compound File (IStorage/IRootStorage)
           implementation using default file-based ILockBytes
           implementation.

  Purpose: Create or open OLE's Compound File (IStorage/IRootStorage)
           implementation using a custom ILockBytes implementation.

  Purpose: Checks if a file is a Compound File with the default
           implementation of ILockBytes or a custom implementation.

  Purpose: Access memory-based ILockBytes implementation.

  Purpose: Access memory-based IStream implementation.

           GetClassFile
  Purpose: Retrieve or save CLSID, data format, and user type information
           to a storage or stream.

  Purpose: Helper function to manipulate Compound File timestamp.

Persistent Objects

Functions: IPersist, IPersistFile, IPersist-Storage, IPersistStream[Init]

  Purpose: Expose from a persistent object based on storage model: file-
           based, IStorage-based, IStream-based (with or without
           initialization).

Notification/Events

Functions: IAdviseSink[2]

  Purpose: Receive notifications of data change, view change, compound
           document object changes.

  Purpose: Receive notifications of property changes and control
           overridable changes.

  Purpose: Interfaces defined by an object, implemented by an outside
           event sink.

Uniform Data Transfer

Functions: IDataObject, (IAdviseSink), IEnumFORMATETC

  Purpose: Expose ability to exchange formatted data structures and notify
           an advise sink of data changes.

  Purpose: Helper function for copying data structures.

  Purpose: Helper to free data structures.

Viewable Objects

Functions: IViewObject[2], (IAdviseSink)

  Purpose: Expose ability to draw visual presentations to device contexts
           and notify an advise sink of view changes.

  Purpose: Simple wrapper around IViewObject::Draw.

           OleGetIconOfClass
  Purpose: Helper function for manipulation of iconic views of objects.

  Purpose: Helper to translates between COLORREF and OLE_COLOR types.

Standard Types

Functions: IFont, IFontDisp

  Purpose: Exposes standard font object implementation (OLE Controls).

  Purpose: Accesses standard font object implementation.

  Purpose: Exposes standard picture object implementation (OLE Controls).

  Purpose: Accesses standard picture object implementation.

  Purpose: Creates a picture object from stream information.

  Purpose: Helper function to turn an icon into a cursor for simple Win32
           API based drag-and-drop (not OLE drag & drop).

OLE Clipboard

Functions: OleSetClipboard, OleGetClipboard, OleFlushClipboard,

           OleIsCurrentClipboard
  Purpose: API for clipboard handling service via IDataObject. No
           customization except for whatever IDataObject implementation is
           involved.

OLE Drag and Drop

Functions: IDropSource

  Purpose: Exposes source-side functionality in a drag & drop operation.

  Purpose: Exposes target-side functionality in a drag & drop operation.

  Purpose: Installs IDropSource (and IDataObject) implementations to begin
           a drag & drop operation.

  Purpose: Installs/uninstalls a drop target implementation. Drop target is
           exposed to DoDragDrop only.

Type Libraries

Functions: ITypeLib, ITypeInfo

  Purpose: Standard OLE implementations to navigate through a type library
           structure.

  Purpose: Standard OLE implementation to bind to interface functions
           defined in a type library in a much more efficient manner,
           useful for compilers.

  Purpose: Create a hash value used in ITypeComp functions.

           RegisterTypeLib, QueryPathOfRegTypeLib
  Purpose: Helpers for registering and loading a type library. Loading a
           type library means instantiating the type library object with
           ITypeLib on it. In other words, Load[Reg]TypeLib[FromResource]
           accesses the standard ITypeLib implementation.

  Purpose: Creates a brand new type library (as opposed to loading an
           existing one). The type library implements ICreateTypeLib.
           Generally used from type library compilers.

  Purpose: Implementations in OLE for creating a type library. Used from
           type library compilers.

  Purpose: Creates an type information object with ITypeInfo based on
           INTERFACEDATA structures.

           GetSystemDefault-[LangID | LCID], GetUser-Default[LangID | LCID]
  Purpose: Helper functions for working with locale-specific information in
           OLE Automation. These are primarily for Win16 platforms as the
           same functions are part of the standard Win32 API.

OLE Automation

Functions: IDispatch, IEnumVARIANT

  Purpose: Expose methods and properties through a dispatch (DISPID)
           mechanism as well as "collections."

  Purpose: Installs a custom interface into a standard IDispatch
           implementation. In other words, accesses a standard IDispatch
           that internally depends on a custom interface implementation.

  Purpose: Helper functions for direct implementations or uses of
           IDispatch.

  Purpose: Helper functions to register automation objects as running and
           access running object. Basically wrappers around the running
           object table.

           Destroy, DestroyData, DestroyDescriptor, GetDim, GetElement,
           GetElemSize, GetLBound, GetUBound, Lock, PutElement, Redim,
           UnAccessData, Unlock
  Purpose: Helper functions for manipulating arrays passed through
           IDispatch.

           ReAllocStringLen, StringLen
  Purpose: Helper functions to manipulate BSTR types.

           TimeToDosDateTime; (DosDateTimeToVarantTime)
  Purpose: Helper functions to manipulate variables passed in VARIANT
           structures, such as type conversion and duplication.

OLE Property Pages

Functions: OleCreatePropertyFrame-[Indirect]

  Purpose: Access standard implementation of a property page frame that
           implements IPropertyPageSite.

  Purpose: Expose capability as a property page frame.

  Purpose: Expose CLSIDs of an object's property pages (which are separate
           objects).

  Purpose: Expose property page functionality.

  Purpose: Expose the ability to manipulate individual properties.

OLE Documents: General

Functions: OleRegGetUserType, OleRegGetMiscStatus, OleRegEnumFormatEtc,

           OleRegEnumVerbs
  Purpose: Helper functions for default registry handling (OLE
           Documents, mostly).

  Purpose: Notifications of when an object is going between loaded and
           running.

           OleSetContainedObject
  Purpose: Helpers for control of running objects in compound documents.
           Most of these functions call IRunnableObject members.

  Purpose: Helper functions for managing IAdviseSink pointers from within a
           compound document object implementation.

  Purpose: Access OLE implementation of IOleAdviseHolder object. No
           customization.

  Purpose: Functions to load and save compound document objects in IStorage
           or IStream instances. Wrappers for IPersistStorage and
           IPersistStream calls.

  Purpose: Access OLE implementation of a static object.

OLE Documents: Handlers and Caching

Functions: OleCreateDefaultHandler, OleCreateEmbeddingHelper

  Purpose: Access OLE implementation of default handler or "embedding
           helper" (a cut-rate default handler for same-process objects).

  Purpose: Implemented by default provided by OLE, in-process handlers and
           servers in compound document uses can customize.

  Purpose: Access OLE's data cache implementation (service). Cache object
           implements a number of interfaces including IOleCache[2],
           IOleCacheControl, IDataObject, IViewObject[2], and
           IPersistStorage.

  Purpose: Implemented in OLE's default handler to access remote server's
           IDataObject implementation. Used in OLE Documents.

OLE Documents: Embedding

Functions: IOleObject

  Purpose: Expose compound document object functionality.

  Purpose: Provide container-side information and functions to compound
           document objects.

           OleQueryCreateFromData
  Purpose: Access custom implementations of embedded compound document
           objects depending on where the source information exists).
           OleQueryCreate-FromData checks if OleCreateFromData will work.

OLE Documents: Linking

Functions: IOleLink

  Purpose: Expose from in-process implementations of linked compound
           document objects (usually taken from OLE's default handler).

           OleQueryCreateLinkFromData
  Purpose: Access custom implementations of linked compound document
           objects depending on where the source information exists).
           OleQueryCreate-LinkFromDat a checks if OleCreateLinkFromData
           will work.

  Purpose: Enumerate objects within a generic container (usually
           compound document container, but not necessarily).
           IOleItemContainer supports the additional step of binding an
           item moniker.

OLE Documents: In-Place Activation

Functions: IOleInPlaceObject, IOleInPlaceActiveObject

  Purpose: Expose object-side functionality for in-place activation support
           (interfaces derive from IOleWindow).

  Purpose: Expose container-side functionality for in-place activation
           support (interfaces derive from IOleWindow).

           OleSetMenuDescriptor, OleTranslateAccelerator
  Purpose: OLE-provided helper functions for in-place activation.

OLE Documents: OLE 1 Compatibility

Functions: CoIsOle1Class

  Purpose: Helper to check if a class is an OLE 1 compound document object.

           OleConvertOLE-STREAMToIStorage[Ex]
  Purpose: Helper functions for a container providing compatibility with
           OLE 1 compound documents.

OLE Controls

Functions: IOleControl

  Purpose: Expose OLE Control specifics to a container dealing with
           keyboard mnemonics and ambient property changes.

  Purpose: Expose OLE Control Container specifics to an OLE Control.

  Purpose: Expose an OLE Control that is merely a visual frame around a set
           of other controls that filters messages going to the controls
           within it to provide group behavior for a set of controls (like
           radio buttons).