Purpose of All OLE APIs and Interfaces

ID: Q126157

1.00 2.00 WINDOWS

The information in this article applies to:

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:

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>

NOTE: The collection of functions in the OLE UI library is not included at this time. Some recently-added interfaces are also missing.

GENERAL

Functions: IUnknown

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

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

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

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

Initialization and Memory Management

Functions: CoBuildVersion, OleBuildVersion

  Purpose: Check OLE library version numbers.

Functions: IMalloc
  Purpose: Task memory allocation.

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

Functions: CoCreateStandardMalloc
  Purpose: Access standard task memory allocator.

Functions: CoGetMalloc
  Purpose: Access currently installed task allocator.

Remoting

Functions: IExternalConnection

  Purpose: Notification - connection/disconnection from remote process.

Functions: CoLockObjectExternal
  Purpose: Lock a remote object implementation.

Functions: CoDisconnectObject
  Purpose: Forcibly disconnect any remote connections.

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

Functions: CoGetStandardMarshal
  Purpose: Access standard implementation of IMarshal.

Functions: IStdMarshalInfo
  Purpose: Support for Custom Interfaces.

Functions: CoMarshalHresult, CoUnmarshalHresult, CoMarshalInterface,
           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.

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

Functions: Custom Interface
  Purpose: Installs a custom IMessageFilter implementation.

Functions: IMessageFilter
  Purpose: Helper functions for OLE 1 container document compatibility.

Functions: CoRegisterMessageFilter
  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.

Functions: IClassFactory[2]
  Purpose: Creation of custom component based on CLSID.

Functions: CoGetClassObject
  Purpose: Access custom class factory implementation given a CLSID.

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

Functions: CoRegisterClassObject, CoRevokeClassObject
  Purpose: Install/remove a custom class factory implementation.

Service Registration

Functions: CoCreateGuid, IsEqualGUID, IsEqualIID, IsEqualCLSID

  Purpose: Helper for creation and comparison of GUIDs.

Functions: DllRegisterServer, DllUnregisterServer
  Purpose: Expose self-registration functionality from a DLL server module.

Functions: CoGetTreatAsClass, CoTreatAsClass, OleDoAutoConvert,
           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.

Functions: CoLoadLibrary, CoFreeLibrary, CoFreeAllLibraries,
           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.

Functions: CoGetCurrentProcess
  Purpose: Miscellaneous helper.

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

Functions: IsValidIid, IsValidInterface, IdValidPtrIn, IsValidPtrOut
  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.

Functions: BindMoniker
  Purpose: Wrapper for IMoniker::BindToObject.

Functions: CreateFileMoniker, CreateItemMoniker, CreateAntiMoniker,
           CreatePointerMoniker, CreateGenericComposite
  Purpose: Access OLE standard moniker implementations.

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

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

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

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

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

Functions: GetRunningObjectTable
  Purpose: Access the running object table.

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

Functions: MonikerRelativePathTo, MonikerCommonPrefixWith
  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).

Functions: IStream
  Purpose: Expose stream object functionality (files).

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

Functions: ILockBytes
  Purpose: Customize underlying storage medium in a Compound File.

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

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

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

Functions: CreateILockBytesOnHGlobal, GetHGlobalFromILockBytes
  Purpose: Access memory-based ILockBytes implementation.

Functions: CreateStreamOnHGlobal, GetHGlobalFromStream.
  Purpose: Access memory-based IStream implementation.

Functions: [Read | Write]Class[Stg | Stm], [Read | Write]FmtUserTypeStg,
           GetClassFile
  Purpose: Retrieve or save CLSID, data format, and user type information
           to a storage or stream.

Functions: StgSetTimes
  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.

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

Functions: Events sets
  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.

Functions: OleDuplicateData
  Purpose: Helper function for copying data structures.

Functions: ReleaseStgMedium
  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.

Functions: OleDraw
  Purpose: Simple wrapper around IViewObject::Draw.

Functions: OleGetIconOfFile, OleMetafilePictFromIconAnd-Label,
           OleGetIconOfClass
  Purpose: Helper function for manipulation of iconic views of objects.

Functions: OleTranslateColor
  Purpose: Helper to translates between COLORREF and OLE_COLOR types.

Standard Types

Functions: IFont, IFontDisp

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

Functions: OleCreateFontIndirect
  Purpose: Accesses standard font object implementation.

Functions: IPicture, IPictureDisp
  Purpose: Exposes standard picture object implementation (OLE Controls).

Functions: OleCreatePictureIndirect
  Purpose: Accesses standard picture object implementation.

Functions: OleLoadPicture
  Purpose: Creates a picture object from stream information.

Functions: OleIconToCursor
  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.

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

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

Functions: RegisterDragDrop, RevokeDragDrop
  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.

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

Functions: LHashValOfName[Sys]
  Purpose: Create a hash value used in ITypeComp functions.

Functions: LoadTypeLib, LoadRegTypeLib, LoadTypeLibFromResource,
           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.

Functions: CreateTypeLib
  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.

Functions: ICreateTypeLib, ICreateTypeInfo
  Purpose: Implementations in OLE for creating a type library. Used from
           type library compilers.

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

Functions: CompareStringA, LCMap-StringA, GetLocaleInfoA, Get-StringTypeA,
           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."

Functions: CreateStdDispatch
  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.

Functions: DispGetIDOfNames, DispGetParams, DispInvoke
  Purpose: Helper functions for direct implementations or uses of
           IDispatch.

Functions: RegisterActiveObject, RevokeActiveObject, GetActiveObject
  Purpose: Helper functions to register automation objects as running and
           access running object. Basically wrappers around the running
           object table.

Functions: SafeArray- AccessData, AllocData, AllocDescriptor, Copy, Create,
           Destroy, DestroyData, DestroyDescriptor, GetDim, GetElement,
           GetElemSize, GetLBound, GetUBound, Lock, PutElement, Redim,
           UnAccessData, Unlock
  Purpose: Helper functions for manipulating arrays passed through
           IDispatch.

Functions: Sys- AllocString, AllocStringLen, FreeString, ReAllocString,
           ReAllocStringLen, StringLen
  Purpose: Helper functions to manipulate BSTR types.

Functions: Variant- ChangeType[Ex], Clear, Copy, CopyInf, Init,
           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.

Functions: IPropertyPageSite
  Purpose: Expose capability as a property page frame.

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

Functions: IPropertyPage[2]
  Purpose: Expose property page functionality.

Functions: IPerPropertyBrowsing
  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).

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

Functions: OleIsRunning, OleLockRunning, OleRun, OleNoteObjectVisible,
           OleSetContainedObject
  Purpose: Helpers for control of running objects in compound documents.
           Most of these functions call IRunnableObject members.

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

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

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

Functions: OleCreateStaticFromData
  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).

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

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

Functions: IOleCacheControl
  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.

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

Functions: OleCreate, OleCreate-FromData, OleCreateFromFile;
           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).

Functions: OleCreateLink, OleCreateLinkFromData, OleCreateLinkToFile;
           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.

Functions: IOleContainer, IOleItemContainer
  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).

Functions: IOleInPlaceFrame, IOleInPlaceUIWindow, IOleInPlaceSite
  Purpose: Expose container-side functionality for in-place activation
           support (interfaces derive from IOleWindow).

Functions: OleCreateMenuDescriptor, OleDestroyMenuDescriptor,
           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.

Functions: OleConvertIStorageToOLE-STREAM[Ex],
           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.

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

Functions: ISimpleFrameSite
  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).

KBCategory: kbref KBSubcategory: ntgeneral Additional reference words: 1.00 2.00 wfwg win
Keywords          : ntgeneral 
Version           : 1.00 2.00
Platform          : WINDOWS

Last Reviewed: September 7, 1996