COleServerItem Class

Article
08/03/2021

Provides the server interface to OLE items.

Syntax

class COleServerItem : public CDocItem

Members

Protected Constructors

Name	Description
COleServerItem::COleServerItem	Constructs a `COleServerItem` object.

Public Methods

Name	Description
COleServerItem::AddOtherClipboardData	Places presentation and conversion formats in a `COleDataSource` object.
COleServerItem::CopyToClipboard	Copies the item to the Clipboard.
COleServerItem::DoDragDrop	Performs a drag-and-drop operation.
COleServerItem::GetClipboardData	Gets the data source for use in data transfer (drag and drop or Clipboard).
COleServerItem::GetDocument	Returns the server document that contains the item.
COleServerItem::GetEmbedSourceData	Gets the CF_EMBEDSOURCE data for an OLE item.
COleServerItem::GetItemName	Returns the name of the item. Used for linked items only.
COleServerItem::GetLinkSourceData	Gets the CF_LINKSOURCE data for an OLE item.
COleServerItem::GetObjectDescriptorData	Gets the CF_OBJECTDESCRIPTOR data for an OLE item.
COleServerItem::IsConnected	Indicates whether the item is currently attached to an active container.
COleServerItem::IsLinkedItem	Indicates whether the item represents a linked OLE item.
COleServerItem::NotifyChanged	Updates all containers with automatic link update.
COleServerItem::OnDoVerb	Called to execute a verb.
COleServerItem::OnDraw	Called when the container requests to draw the item; implementation required.
COleServerItem::OnDrawEx	Called for specialized item drawing.
COleServerItem::OnGetClipboardData	Called by the framework to get the data that would be copied to the Clipboard.
COleServerItem::OnGetExtent	Called by the framework to retrieve the size of the OLE item.
COleServerItem::OnInitFromData	Called by the framework to initialize an OLE item using the contents of the data transfer object specified.
COleServerItem::OnQueryUpdateItems	Called to determine whether any linked items require updating.
COleServerItem::OnRenderData	Retrieves data as part of delayed rendering.
COleServerItem::OnRenderFileData	Retrieves data into a `CFile` object as part of delayed rendering.
COleServerItem::OnRenderGlobalData	Retrieves data into an HGLOBAL as part of delayed rendering.
COleServerItem::OnSetColorScheme	Called to set the item's color scheme.
COleServerItem::OnSetData	Called to set the item's data.
COleServerItem::OnSetExtent	Called by the framework to set the size of the OLE item.
COleServerItem::OnUpdate	Called when some portion of the document the item belongs in is changed.
COleServerItem::OnUpdateItems	Called to update the presentation cache of all items in the server document.
COleServerItem::SetItemName	Sets the name of the item. Used for linked items only.

Protected Methods

Name	Description
COleServerItem::GetDataSource	Gets the object used to store conversion formats.
COleServerItem::OnHide	Called by the framework to hide the OLE item.
COleServerItem::OnOpen	Called by the framework to display the OLE item in its own top-level window.
COleServerItem::OnShow	Called when the container requests to show the item.

Public Data Members

Name	Description
COleServerItem::m_sizeExtent	Informs the server about how much of the OLE item is visible.

Remarks

A linked item can represent some or all of a server document. An embedded item always represents an entire server document.

The COleServerItem class defines several overridable member functions that are called by the OLE system dynamic-link libraries (DLLs), usually in response to requests from the container application. These member functions allow the container application to manipulate the item indirectly in various ways, such as by displaying it, executing its verbs, or retrieving its data in various formats.

To use COleServerItem, derive a class from it and implement the OnDraw and Serialize member functions. The OnDraw function provides the metafile representation of an item, allowing it to be displayed when a container application opens a compound document. The Serialize function of CObject provides the native representation of an item, allowing an embedded item to be transferred between the server and container applications. OnGetExtent provides the natural size of the item to the container, enabling the container to size the item.

For more information about servers and related topics, see the article Servers: Implementing a Server and "Creating a Container/Server Application" in the article Containers: Advanced Features.

Inheritance Hierarchy

CObject

CCmdTarget

CDocItem

COleServerItem

Requirements

Header: afxole.h

COleServerItem::AddOtherClipboardData

Call this function to place the presentation and conversion formats for the OLE item in the specified COleDataSource object.

void AddOtherClipboardData(COleDataSource* pDataSource);

Parameters

pDataSource
Pointer to the COleDataSource object in which the data should be placed.

Remarks

You must have implemented the OnDraw member function to provide the presentation format (a metafile picture) for the item. To support other conversion formats, register them using the COleDataSource object returned by GetDataSource and override the OnRenderData member function to provide data in the formats you want to support.

COleServerItem::COleServerItem

Constructs a COleServerItem object and adds it to the server document's collection of document items.

COleServerItem(
    COleServerDoc* pServerDoc,
    BOOL bAutoDelete);

Parameters

pServerDoc
Pointer to the document that will contain the new item.

bAutoDelete
Flag indicating whether the object can be deleted when a link to it is released. Set this to FALSE if the COleServerItem object is an integral part of your document's data which you must delete. Set this to TRUE if the object is a secondary structure used to identify a range in your document's data that can be deleted by the framework.

COleServerItem::CopyToClipboard

Call this function to copy the OLE item to the Clipboard.

void CopyToClipboard(BOOL bIncludeLink = FALSE);

Parameters

bIncludeLink
Set this to TRUE if link data should be copied to the Clipboard. Set this to FALSE if your server application does not support links.

Remarks

The function uses the OnGetClipboardData member function to create a COleDataSource object containing the OLE item's data in the formats supported. The function then places the COleDataSource object on the Clipboard by using the COleDataSource::SetClipboard function. The COleDataSource object includes the item's native data and its representation in CF_METAFILEPICT format, as well as data in any conversion formats you choose to support. You must have implemented Serialize and OnDraw for this member function to work.

COleServerItem::DoDragDrop

Call the DoDragDrop member function to perform a drag-and-drop operation.

DROPEFFECT DoDragDrop(
    LPCRECT lpRectItem,
    CPoint ptOffset,
    BOOL bIncludeLink = FALSE,
    DWORD dwEffects = DROPEFFECT_COPY | DROPEFFECT_MOVE,
    LPCRECT lpRectStartDrag = NULL);

Parameters

lpRectItem
The item's rectangle on screen, in pixels, relative to the client area.

ptOffset
The offset from lpItemRect where the mouse position was at the time of the drag.

bIncludeLink
Set this to TRUE if link data should be copied to the Clipboard. Set it to FALSE if your application does not support links.

dwEffects
Determines the effects that the drag source will allow in the drag operation (a combination of Copy, Move, and Link).

lpRectStartDrag
Pointer to the rectangle that defines where the drag actually starts. For more information, see the following Remarks section.

Return Value

A value from the DROPEFFECT enumeration. If it is DROPEFFECT_MOVE, the original data should be removed.

Remarks

The drag-and-drop operation does not start immediately. It waits until the mouse cursor leaves the rectangle specified by lpRectStartDrag or until a specified number of milliseconds have passed. If lpRectStartDrag is NULL, a default rectangle is used so that the drag starts when the mouse cursor moves one pixel.

The delay time is specified by a registry key setting. You can change the delay time by calling CWinApp::WriteProfileString or CWinApp::WriteProfileInt. If you do not specify the delay time, a default value of 200 milliseconds is used. Drag delay time is stored as follows:

Windows NT Drag delay time is stored in HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\NT\CurrentVersion\IniFileMapping\win.ini\Windows\DragDelay.
Windows 3.x Drag delay time is stored in the WIN.INI file, under the [Windows} section.
Windows 95/98 Drag delay time is stored in a cached version of WIN.INI.

For more information about how drag delay information is stored in either the registry or the .INI file, see WriteProfileString in the Windows SDK.

COleServerItem::GetClipboardData

Call this function to fill the specified COleDataSource object with all the data that would be copied to the Clipboard if you called CopyToClipboard (the same data would also be transferred if you called DoDragDrop).

void GetClipboardData(
    COleDataSource* pDataSource,
    BOOL bIncludeLink = FALSE,
    LPPOINT lpOffset = NULL,
    LPSIZE lpSize = NULL);

Parameters

pDataSource
Pointer to the COleDataSource object that will receive the OLE item's data in all supported formats.

bIncludeLink
TRUE if link data should be copied to the Clipboard. FALSE if your server application does not support links.

lpOffset
The offset, in pixels, of the mouse cursor from the origin of the object.

lpSize
The size of the object in pixels.

Remarks

This function calls the GetEmbedSourceData member function to get the native data for the OLE item and calls the AddOtherClipboardData member function to get the presentation format and any supported conversion formats. If bIncludeLink is TRUE, the function also calls GetLinkSourceData to get the link data for the item.

Override this function if you want to put formats in a COleDataSource object before or after those formats supplied by CopyToClipboard.

COleServerItem::GetDataSource

Call this function to get the COleDataSource object used to store the conversion formats that the server application supports.

COleDataSource* GetDataSource();

Return Value

A pointer to the COleDataSource object used to store the conversion formats.

Remarks

If you want your server application to offer data in a variety of formats during data transfer operations, register those formats with the COleDataSource object returned by this function. For example, if you want to supply a CF_TEXT representation of the OLE item for Clipboard or drag-and-drop operations, you would register the format with the COleDataSource object this function returns, and then override the OnRenderXxxData member function to provide the data.

COleServerItem::GetDocument

Call this function to get a pointer to the document that contains the item.

COleServerDoc* GetDocument() const;

Return Value

A pointer to the document that contains the item; NULL if the item is not part of a document.

Remarks

This allows access to the server document that you passed as an argument to the COleServerItem constructor.

COleServerItem::GetEmbedSourceData

Call this function to get the CF_EMBEDSOURCE data for an OLE item.

void GetEmbedSourceData(LPSTGMEDIUM lpStgMedium);

Parameters

lpStgMedium
Pointer to the STGMEDIUM structure that will receive the CF_EMBEDSOURCE data for the OLE item.

Remarks

This format includes the item's native data. You must have implemented the Serialize member function for this function to work properly.

The result can then be added to a data source by using COleDataSource::CacheData. This function is called automatically by COleServerItem::OnGetClipboardData.

For more information, see STGMEDIUM in the Windows SDK.

COleServerItem::GetItemName

Call this function to get the name of the item.

const CString& GetItemName() const;

Return Value

The name of the item.

Remarks

You typically call this function only for linked items.

COleServerItem::GetLinkSourceData

Call this function to get the CF_LINKSOURCE data for an OLE item.

BOOL GetLinkSourceData(LPSTGMEDIUM lpStgMedium);

Parameters

lpStgMedium
Pointer to the STGMEDIUM structure that will receive the CF_LINKSOURCE data for the OLE item.

Return Value

Nonzero if successful; otherwise 0.

Remarks

This format includes the CLSID describing the type of the OLE item and the information needed to locate the document containing the OLE item.

The result can then be added to a data source with COleDataSource::CacheData. This function is called automatically by OnGetClipboardData.

For more information, see STGMEDIUM in the Windows SDK.

COleServerItem::GetObjectDescriptorData

Call this function to get the CF_OBJECTDESCRIPTOR data for an OLE item.

void GetObjectDescriptorData(
    LPPOINT lpOffset,
    LPSIZE lpSize,
    LPSTGMEDIUM lpStgMedium);

Parameters

lpOffset
Offset of the mouse click from the upper-left corner of the OLE item. Can be NULL.

lpSize
Size of the OLE item. Can be NULL.

lpStgMedium
Pointer to the STGMEDIUM structure that will receive the CF_OBJECTDESCRIPTOR data for the OLE item.

Remarks

The information is copied into the STGMEDIUM structure pointed to by lpStgMedium. This format includes the information needed for the Paste Special dialog.

For more information, see STGMEDIUM in the Windows SDK.

COleServerItem::IsConnected

Call this function to see if the OLE item is connected.

BOOL IsConnected() const;

Return Value

Nonzero if the item is connected; otherwise 0.

Remarks

An OLE item is considered connected if one or more containers have references to the item. An item is connected if its reference count is greater than 0 or if it is an embedded item.

COleServerItem::IsLinkedItem

Call this function to see if the OLE item is a linked item.

BOOL IsLinkedItem() const;

Return Value

Nonzero if the item is a linked item; otherwise 0.

Remarks

An item is linked if the item is valid and is not returned in the document's list of embedded items. A linked item might or might not be connected to a container.

It is common to use the same class for both linked and embedded items. IsLinkedItem allows you to make linked items behave differently than embedded items, although many times the code is common.

COleServerItem::m_sizeExtent

This member tells the server how much of the object is visible in the container document.

CSize m_sizeExtent;

Remarks

The default implementation of OnSetExtent sets this member.

COleServerItem::NotifyChanged

Call this function after the linked item has been changed.

void NotifyChanged(DVASPECT nDrawAspect = DVASPECT_CONTENT);

Parameters

nDrawAspect
A value from the DVASPECT enumeration that indicates which aspect of the OLE item has changed. This parameter can have any of the following values:

DVASPECT_CONTENT Item is represented in such a way that it can be displayed as an embedded object inside its container.
DVASPECT_THUMBNAIL Item is rendered in a "thumbnail" representation so that it can be displayed in a browsing tool.
DVASPECT_ICON Item is represented by an icon.
DVASPECT_DOCPRINT Item is represented as if it were printed using the Print command from the File menu.

Remarks

If a container item is linked to the document with an automatic link, the item is updated to reflect the changes. In container applications written using the Microsoft Foundation Class Library, COleClientItem::OnChange is called in response.

COleServerItem::OnDoVerb

Called by the framework to execute the specified verb.

virtual void OnDoVerb(LONG iVerb);

Parameters

iVerb
Specifies the verb to execute. It can be any one of the following:

Value	Meaning	Symbol
0	Primary verb	OLEIVERB_PRIMARY
1	Secondary verb	(None)
- 1	Display item for editing	OLEIVERB_SHOW
- 2	Edit item in separate window	OLEIVERB_OPEN
- 3	Hide item	OLEIVERB_HIDE

The -1 value is typically an alias for another verb. If open editing is not supported, -2 has the same effect as -1. For additional values, see IOleObject::DoVerb in the Windows SDK.

Remarks

If the container application was written with the Microsoft Foundation Class Library, this function is called when the COleClientItem::Activate member function of the corresponding COleClientItem object is called. The default implementation calls the OnShow member function if the primary verb or OLEIVERB_SHOW is specified, OnOpen if the secondary verb or OLEIVERB_OPEN is specified, and OnHide if OLEIVERB_HIDE is specified. The default implementation calls OnShow if iVerb is not one of the verbs listed above.

Override this function if your primary verb does not show the item. For example, if the item is a sound recording and its primary verb is Play, you would not have to display the server application to play the item.

For more information, see IOleObject::DoVerb in the Windows SDK.

COleServerItem::OnDraw

Called by the framework to render the OLE item into a metafile.

virtual BOOL OnDraw(
    CDC* pDC,
    CSize& rSize) = 0;

Parameters

pDC
A pointer to the CDC object on which to draw the item. The display context is automatically connected to the attribute display context so you can call attribute functions, although doing so would make the metafile device-specific.

rSize
Size, in HIMETRIC units, in which to draw the metafile.

Return Value

Nonzero if the item was successfully drawn; otherwise 0.

Remarks

The metafile representation of the OLE item is used to display the item in the container application. If the container application was written with the Microsoft Foundation Class Library, the metafile is used by the Draw member function of the corresponding COleClientItem object. There is no default implementation. You must override this function to draw the item into the device context specified.

COleServerItem::OnDrawEx

Called by the framework for all drawing.

virtual BOOL OnDrawEx(
    CDC* pDC,
    DVASPECT nDrawAspect,
    CSize& rSize);

Parameters

pDC
A pointer to the CDC object on which to draw the item. The DC is automatically connected to the attribute DC so you can call attribute functions, although doing so would make the metafile device-specific.

nDrawAspect
A value from the DVASPECT enumeration. This parameter can have any of the following values:

DVASPECT_CONTENT Item is represented in such a way that it can be displayed as an embedded object inside its container.
DVASPECT_THUMBNAIL Item is rendered in a "thumbnail" representation so that it can be displayed in a browsing tool.
DVASPECT_ICON Item is represented by an icon.
DVASPECT_DOCPRINT Item is represented as if it were printed using the Print command from the File menu.

rSize
Size of the item in HIMETRIC units.

Return Value

Nonzero if the item was successfully drawn; otherwise 0.

Remarks

The default implementation calls OnDraw when DVASPECT is equal to DVASPECT_CONTENT; otherwise it fails.

Override this function to provide presentation data for aspects other than DVASPECT_CONTENT, such as DVASPECT_ICON or DVASPECT_THUMBNAIL.

COleServerItem::OnGetClipboardData

Called by the framework to get a COleDataSource object containing all the data that would be placed on the Clipboard by a call to the CopyToClipboard member function.

virtual COleDataSource* OnGetClipboardData(
    BOOL bIncludeLink,
    LPPOINT lpOffset,
    LPSIZE lpSize);

Parameters

bIncludeLink
Set this to TRUE if link data should be copied to the Clipboard. Set this to FALSE if your server application does not support links.

lpOffset
The offset of the mouse cursor from the origin of the object in pixels.

lpSize
The size of the object in pixels.

Return Value

A pointer to a COleDataSource object containing the Clipboard data.

Remarks

The default implementation of this function calls GetClipboardData.

COleServerItem::OnGetExtent

Called by the framework to retrieve the size, in HIMETRIC units, of the OLE item.

virtual BOOL OnGetExtent(
    DVASPECT nDrawAspect,
    CSize& rSize);

Parameters

nDrawAspect
Specifies the aspect of the OLE item whose bounds are to be retrieved. This parameter can have any of the following values:

DVASPECT_CONTENT Item is represented in such a way that it can be displayed as an embedded object inside its container.
DVASPECT_THUMBNAIL Item is rendered in a "thumbnail" representation so that it can be displayed in a browsing tool.
DVASPECT_ICON Item is represented by an icon.
DVASPECT_DOCPRINT Item is represented as if it were printed using the Print command from the File menu.

rSize
Reference to a CSize object that will receive the size of the OLE item.

Return Value

Nonzero if successful; otherwise 0.

Remarks

If the container application was written with the Microsoft Foundation Class Library, this function is called when the GetExtent member function of the corresponding COleClientItem object is called. The default implementation does nothing. You must implement it yourself. Override this function if you want to perform special processing when handling a request for the size of the OLE item.

COleServerItem::OnHide

Called by the framework to hide the OLE item.

virtual void OnHide();

Remarks

The default calls COleServerDoc::OnShowDocument( FALSE ). The function also notifies the container that the OLE item has been hidden. Override this function if you want to perform special processing when hiding an OLE item.

COleServerItem::OnInitFromData

Called by the framework to initialize an OLE item using the contents of pDataObject.

virtual BOOL OnInitFromData(
    COleDataObject* pDataObject,
    BOOL bCreation);

Parameters

pDataObject
Pointer to an OLE data object containing data in various formats for initializing the OLE item.

bCreation
TRUE if the function is called to initialize an OLE item being newly created by a container application. FALSE if the function is called to replace the contents of an already existing OLE item.

Return Value

Nonzero if successful; otherwise 0.

Remarks

If bCreation is TRUE, this function is called if a container implements Insert New Object based on the current selection. The data selected is used when creating the new OLE item. For example, when selecting a range of cells in a spreadsheet program and then using the Insert New Object to create a chart based on the values in the selected range. The default implementation does nothing. Override this function to choose an acceptable format from those offered by pDataObject and initialize the OLE item based on the data provided. This is an advanced overridable.

For more information, see IOleObject::InitFromData in the Windows SDK.

COleServerItem::OnOpen

Called by the framework to display the OLE item in a separate instance of the server application, rather than in place.

virtual void OnOpen();

Remarks

The default implementation activates the first frame window displaying the document that contains the OLE item; if the application is a mini-server, the default implementation shows the main window. The function also notifies the container that the OLE item has been opened.

Override this function if you want to perform special processing when opening an OLE item. This is especially common with linked items where you want to set the selection to the link when it is opened.

For more information, see IOleClientSite::OnShowWindow in the Windows SDK.

COleServerItem::OnQueryUpdateItems

Called by the framework to determine whether any linked items in the current server document are out of date.

virtual BOOL OnQueryUpdateItems();

Return Value

Nonzero if the document has items needing updates; 0 if all items are up to date.

Remarks

An item is out of date if its source document has been changed but the linked item has not been updated to reflect the changes in the document.

COleServerItem::OnRenderData

Called by the framework to retrieve data in the specified format.

virtual BOOL OnRenderData(
    LPFORMATETC lpFormatEtc,
    LPSTGMEDIUM lpStgMedium);

Parameters

lpFormatEtc
Points to the FORMATETC structure specifying the format in which information is requested.

lpStgMedium
Points to a STGMEDIUM structure in which the data is to be returned.

Return Value

Nonzero if successful; otherwise 0.

Remarks

The specified format is one previously placed in the COleDataSource object using the DelayRenderData or DelayRenderFileData member function for delayed rendering. The default implementation of this function calls OnRenderFileData or OnRenderGlobalData, respectively, if the supplied storage medium is either a file or memory. If neither of these formats is supplied, the default implementation returns 0 and does nothing.

If lpStgMedium-> tymed is TYMED_NULL, the STGMEDIUM should allocated and filled as specified by lpFormatEtc->tymed. If not TYMED_NULL, the STGMEDIUM should be filled in place with the data.

This is an advanced overridable. Override this function to provide your data in the requested format and medium. Depending on your data, you may want to override one of the other versions of this function instead. If your data is small and fixed in size, override OnRenderGlobalData. If your data is in a file, or is of variable size, override OnRenderFileData.

For more information, see IDataObject::GetData, STGMEDIUM, FORMATETC, and TYMED in the Windows SDK.

COleServerItem::OnRenderFileData

Called by the framework to retrieve data in the specified format when the storage medium is a file.

virtual BOOL OnRenderFileData(
    LPFORMATETC lpFormatEtc,
    CFile* pFile);

Parameters

lpFormatEtc
Points to the FORMATETC structure specifying the format in which information is requested.

pFile
Points to a CFile object in which the data is to be rendered.

Return Value

Nonzero if successful; otherwise 0.

Remarks

The specified format is one previously placed in the COleDataSource object using the DelayRenderData member function for delayed rendering. The default implementation of this function simply returns FALSE.

This is an advanced overridable. Override this function to provide your data in the requested format and medium. Depending on your data, you might want to override one of the other versions of this function instead. If you want to handle multiple storage mediums, override OnRenderData. If your data is in a file, or is of variable size, override OnRenderFileData.

For more information, see IDataObject::GetData and FORMATETC in the Windows SDK.

COleServerItem::OnRenderGlobalData

Called by the framework to retrieve data in the specified format when the specified storage medium is global memory.

virtual BOOL OnRenderGlobalData(
    LPFORMATETC lpFormatEtc,
    HGLOBAL* phGlobal);

Parameters

lpFormatEtc
Points to the FORMATETC structure specifying the format in which information is requested.

phGlobal
Points to a handle to global memory in which the data is to be returned. If no memory has been allocated, this parameter can be NULL.

Return Value

Nonzero if successful; otherwise 0.

Remarks

If phGlobal is NULL, then a new HGLOBAL should be allocated and returned in phGlobal. Otherwise, the HGLOBAL specified by phGlobal should be filled with the data. The amount of data placed in the HGLOBAL must not exceed the current size of the memory block. Also, the block cannot be reallocated to a larger size.

This is an advanced overridable. Override this function to provide your data in the requested format and medium. Depending on your data, you may want to override one of the other versions of this function instead. If you want to handle multiple storage mediums, override OnRenderData. If your data is in a file, or is of variable size, override OnRenderFileData.

For more information, see IDataObject::GetData and FORMATETC in the Windows SDK.

COleServerItem::OnSetColorScheme

Called by the framework to specify a color palette to be used when editing the OLE item.

virtual BOOL OnSetColorScheme(const LOGPALETTE* lpLogPalette);

Parameters

lpLogPalette
Pointer to a Windows LOGPALETTE structure.

Return Value

Nonzero if the color palette is used; otherwise 0.

Remarks

If the container application was written using the Microsoft Foundation Class Library, this function is called when the IOleObject::SetColorScheme function of the corresponding COleClientItem object is called. The default implementation returns FALSE. Override this function if you want to use the recommended palette. The server application is not required to use the suggested palette.

For more information, see IOleObject::SetColorScheme in the Windows SDK.

COleServerItem::OnSetData

Called by the framework to replace the OLE item's data with the specified data.

virtual BOOL OnSetData(
    LPFORMATETC lpFormatEtc,
    LPSTGMEDIUM lpStgMedium,
    BOOL bRelease);

Parameters

lpFormatEtc
Pointer to a FORMATETC structure specifying the format of the data.

lpStgMedium
Pointer to a STGMEDIUM structure in which the data resides.

bRelease
Indicates who has ownership of the storage medium after completing the function call. The caller decides who is responsible for releasing the resources allocated on behalf of the storage medium. The caller does this by setting bRelease. If bRelease is nonzero, the server item takes ownership, freeing the medium when it has finished using it. When bRelease is 0, the caller retains ownership and the server item can use the storage medium only for the duration of the call.

Return Value

Nonzero if successful; otherwise 0.

Remarks

The server item does not take ownership of the data until it has successfully obtained it. That is, it does not take ownership if it returns 0. If the data source takes ownership, it frees the storage medium by calling the ReleaseStgMedium function.

The default implementation does nothing. Override this function to replace the OLE item's data with the specified data. This is an advanced overridable.

For more information, see STGMEDIUM, FORMATETC, and ReleaseStgMedium in the Windows SDK.

COleServerItem::OnSetExtent

Called by the framework to tell the OLE item how much space is available to it in the container document.

virtual BOOL OnSetExtent(
    DVASPECT nDrawAspect,
    const CSize& size);

Parameters

nDrawAspect
Specifies the aspect of the OLE item whose bounds are being specified. This parameter can have any of the following values:

DVASPECT_CONTENT Item is represented in such a way that it can be displayed as an embedded object inside its container.
DVASPECT_THUMBNAIL Item is rendered in a "thumbnail" representation so that it can be displayed in a browsing tool.
DVASPECT_ICON Item is represented by an icon.
DVASPECT_DOCPRINT Item is represented as if it were printed using the Print command from the File menu.

size
A CSize structure specifying the new size of the OLE item.

Return Value

Nonzero if successful; otherwise 0.

Remarks

If the container application was written with the Microsoft Foundation Class Library, this function is called when the SetExtent member function of the corresponding COleClientItem object is called. The default implementation sets the m_sizeExtent member to the specified size if nDrawAspect is DVASPECT_CONTENT; otherwise it returns 0. Override this function to perform special processing when you change the size of the item.

COleServerItem::OnShow

Called by the framework to instruct the server application to display the OLE item in place.

virtual void OnShow();

Remarks

This function is typically called when the user of the container application creates an item or executes a verb, such as Edit, that requires the item to be shown. The default implementation attempts in-place activation. If this fails, the function calls the OnOpen member function to display the OLE item in a separate window.

Override this function if you want to perform special processing when an OLE item is shown.

COleServerItem::OnUpdate

Called by the framework when an item has been modified.

virtual void OnUpdate(
    COleServerItem* pSender,
    LPARAM lHint,
    CObject* pHint,
    DVASPECT nDrawAspect);

Parameters

pSender
Pointer to the item that modified the document. Can be NULL.

lHint
Contains information about the modification.

pHint
Pointer to an object storing information about the modification.

nDrawAspect
A value from the DVASPECT enumeration. This parameter can have any one of the following values:

DVASPECT_CONTENT Item is represented in such a way that it can be displayed as an embedded object inside its container.
DVASPECT_THUMBNAIL Item is rendered in a "thumbnail" representation so that it can be displayed in a browsing tool.
DVASPECT_ICON Item is represented by an icon.
DVASPECT_DOCPRINT Item is represented as if it were printed using the Print command from the File menu.

Remarks

The default implementation calls NotifyChanged, regardless of the hint or sender.

COleServerItem::OnUpdateItems

Called by the framework to update all items in the server document.

virtual void OnUpdateItems();

Remarks

The default implementation calls UpdateLink for all COleClientItem objects in the document.

COleServerItem::SetItemName

Call this function when you create a linked item to set its name.

void SetItemName(LPCTSTR lpszItemName);

Parameters

lpszItemName
Pointer to the new name of the item.

Remarks

The name must be unique within the document. When a server application is called to edit a linked item, the application uses this name to find the item. You do not need to call this function for embedded items.