OleCreate
Creates an embedded object identified by a CLSID. You use it typically to
implement the menu item that allows the end user to insert a new object.
STDAPI OleCreate(
REFCLSID rclsid,
| //CLSID of embedded object to be created
|
REFIID riid,
| //Interface used to communicate with new object
|
DWORD renderopt,
| //RENDEROPT value indicating cached capabilities
|
FORMATETC * pFormatEtc,
| //FORMATETC value, depending upon RENDEROPT value
|
IOleClientSite * pClientSite,
| //Client site pointer to request services from the container
|
IStorage * pStg,
| //IStorage instance to be used as storage for the object
|
void ** ppvObject
| //On return, pointer to new object
|
);
|
|
Parameters
rclsid
Specifies the CLSID of the embedded object that is to be created.
riid
Identifies the interface, usually
IID_IOleObject, through which the caller will communicate with the new object.
renderopt
A value from the enumeration
OLERENDER, indicating the locally cached drawing capabilities the newly created object
is to have. The
OLERENDER value chosen affects the possible values for the
pFormatEtc parameter.
pFormatEtc
Depending on which of the
OLERENDER flags is used as the value of
renderopt, may be one of the
FORMATETC enumeration values. Refer to the
OLERENDER enumeration for restrictions. This parameter, along with the
renderopt parameter, specifies what the new object can cache initially.
pClientSite
Points to an instance of
IOleClientSite, the primary interface through which the object will request services from
its container. Value may be NULL.
pStg
Points to an instance of the
IStorage interface to be used as the storage for the object. This parameter may not be
NULL.
ppvObject
Upon successful return, receives a pointer to the interface requested in
riid on the newly created object.
Return Values
S_OK
Indicates embedded object created successfully.
E_OUTOFMEMORY
Indicates embedded object cannot be created due to lack of memory.
Comments
The
OleCreate function creates a new embedded object, and is typically called to implement
the menu item Insert New Object
. When
OleCreate returns, the object it has created is blank (contains no data), unless
renderopt is OLERENDER_DRAW or OLERENDER_FORMAT, and is loaded. Containers typically
then call the
OleRun function or
IOleObject::DoVerb to show the object for initial editing.
The
rclsid parameter specifies the CLSID of the requested object. CLSIDs of registered
objects are stored in the registry. When an application user selects Insert
Object, a selection box allows the user to select the type of object desired from
those in the system registry. When
OleCreate is used to implement the Insert Object menu item, the CLSID associated with
the selected item is assigned to the
rclsid parameter of
OleCreate.
The
riid parameter specifies the interface the client will use to communicate with the
new object. Upon successful return, the
ppvObject parameter holds a pointer to the requested interface.
The created object's cache contains information that allows a presentation of
a contained object when the container is opened. Information about what should
be cached is passed in the
renderopt and
pFormatetc values. When
OleCreate returns, the created object's cache is not necessarily filled. Instead, the
cache is filled the first time the object enters the running state. The caller
can add additional cache control with a call to
IOleCache::Cache after the return of
OleCreate and before the object is run. If
renderopt is OLERENDER_DRAW or OLERENDER_FORMAT,
OleCreate requires that the object support the
IOleCache interface. There is no such requirement for any other value of
renderopt.
If
pClientSite is non-NULL,
OleCreate calls
IOleObject::SetClientSite with the
pClientSite parameter.
IOleClientSite is the primary interface by which an object requests services from its
container.
If
pClientSite is NULL, you must make a specific call to
IOleObject::SetClientSite before attempting any operations.
See Also
OLERENDER,
FORMATETC,
IOleClientSite,
IOleObject
- Software for developers
-
Delphi Components
.Net Components
Software for Android Developers
- More information resources
-
MegaDetailed.Net
Unix Manual Pages
Delphi Examples
