Purpose of All OLE APIs and Interfaces

ID: Q126157

The information in this article applies to:

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>

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 : ntgeneral
Version :
Platform : WINDOWS
Issue type :