Microsoft KB Archive/126157

= Purpose of All OLE APIs and Interfaces =

Article ID: 126157

Article Last Modified on 10/3/2003

-

APPLIES TO


 * Microsoft OLE 1.0
 * Microsoft OLE 2.01
 * Microsoft OLE 2.03

-



This article was previously published under Q126157



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: 

Purpose: 

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: lUnknown

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

Additional query words: 1.00 2.00 wfwg win

Keywords: KB126157

-

[mailto:TECHNET@MICROSOFT.COM Send feedback to Microsoft]

© Microsoft Corporation. All rights reserved.