Función OleCreateEx (ole2.h)

Artículo
08/25/2023

Amplía la funcionalidad OleCreate al admitir una creación de instancias más eficaz de objetos en contenedores que requieren almacenamiento en caché de varios formatos de presentación o datos, en lugar del formato único admitido por OleCreate.

Sintaxis

HRESULT OleCreateEx(
  [in]  REFCLSID        rclsid,
  [in]  REFIID          riid,
  [in]  DWORD           dwFlags,
  [in]  DWORD           renderopt,
  [in]  ULONG           cFormats,
  [in]  DWORD           *rgAdvf,
  [in]  LPFORMATETC     rgFormatEtc,
  [in]  IAdviseSink     *lpAdviseSink,
  [out] DWORD           *rgdwConnection,
  [in]  LPOLECLIENTSITE pClientSite,
  [in]  LPSTORAGE       pStg,
  [out] LPVOID          *ppvObj
);

Parámetros

[in] rclsid

Identifica la clase del objeto que se va a crear.

[in] riid

Referencia al identificador de la interfaz del objeto que se va a devolver.

[in] dwFlags

Este valor puede ser 0 o OLECREATE_LEAVERUNNING (0x00000001).

[in] renderopt

Valor tomado de la enumeración OLERENDER .

[in] cFormats

Cuando renderopt es OLERENDER_FORMAT, indica el número de estructuras FORMATETC en la matriz rgFormatEtc , que debe ser al menos una. En todos los demás casos, este parámetro debe ser cero.

[in] rgAdvf

Cuando renderopt se OLERENDER_FORMAT, apunta a una matriz de elementos DWORD cFormats, cada uno de los cuales es una combinación de valores de la enumeración ADVF . Cada elemento de esta matriz se pasa como parámetro advf a una llamada a IOleCache::Cache o IDataObject::D Advise, dependiendo de si pAdviseSink es NULL o no NULL (consulte a continuación). En todos los demás casos, este parámetro debe ser NULL.

[in] rgFormatEtc

Cuando renderopt se OLERENDER_FORMAT, apunta a una matriz de estructuras FORMATETC de cFormats. Cuando pAdviseSink es NULL, cada elemento de esta matriz se pasa como parámetro pFormatEtc a una llamada a la IOleCache::Cache del objeto. Esto rellena la caché de datos y presentaciones administrada por el controlador de objetos en proceso (normalmente el controlador predeterminado) con presentación u otros datos almacenables en caché. Cuando pAdviseSink no es NULL, cada elemento de esta matriz se pasa como parámetro pFormatEtc a una llamada a IDataObject::D Advise. Esto permite al autor de la llamada (normalmente un contenedor OLE) realizar su propio almacenamiento en caché o procesamiento de los datos recibidos del objeto. En todos los demás casos, este parámetro debe ser NULL.

[in] lpAdviseSink

Cuando renderopt es OLERENDER_FORMAT, puede ser un puntero IAdviseSink válido, que indica el almacenamiento en caché personalizado o el procesamiento de avisos de datos, o NULL, que indica el almacenamiento en caché predeterminado de formatos de datos. En todos los demás casos, este parámetro debe ser NULL.

[out] rgdwConnection

Ubicación para devolver la matriz de valores dwConnection devueltos cuando la interfaz pAdviseSink se registra para cada conexión de asesoramiento mediante IDataObject::D Advise o NULL si no se necesitan las conexiones de asesoramiento devueltas. Debe ser NULL, si pAdviseSink es NULL.

[in] pClientSite

Puntero a la interfaz principal a través de la cual el objeto solicitará servicios de su contenedor. Este parámetro puede ser NULL, en cuyo caso es responsabilidad del autor de la llamada establecer el sitio cliente lo antes posible mediante IOleObject::SetClientSite.

[in] pStg

Puntero al almacenamiento que se va a usar para el objeto y cualquier dato predeterminado o almacenamiento en caché de presentaciones establecido para él. Este parámetro puede no ser NULL.

[out] ppvObj

Dirección de la variable de puntero de salida que recibe el puntero de interfaz solicitado en riid. Tras la devolución correcta, *ppvObj contiene el puntero de interfaz solicitado en el objeto recién creado.

Valor devuelto

Esta función devuelve S_OK si se ejecuta correctamente. Otros valores posibles son los siguientes.

Código devuelto	Descripción
E_NOINTERFACE	El identificador de interfaz proporcionado no es válido.

Comentarios

La siguiente llamada a OleCreate:

OleCreate(rclsid, riid, renderopt, pFormatEtc, pClientSite, pStg, ppvObj);

es equivalente a la siguiente llamada a OleCreateEx:

DWORD    advf = ADVF_PRIMEFIRST;
    OleCreateEx(rclsid, riid, renderopt, 1, &amp;advf, pFormatEtc, NULL, pClientSite, pStg, ppvObj);

Las funciones de creación de instancias existentes, (OleCreate, OleCreateFromFile, OleCreateFromData, OleCreateLink, OleCreateLinkToFile y OleCreateLinkFromData) crean solo una sola presentación o caché de formato de datos en la ubicación de caché predeterminada (dentro de las secuencias '\001OlePresXXX' del IStorage pasado), durante la creación de instancias. Además, estas memorias caché deben crearse cuando el objeto entra en estado en ejecución. Dado que la mayoría de las aplicaciones requieren almacenamiento en caché al menos dos presentaciones (pantalla e impresora) y pueden requerir almacenamiento en caché de datos en un formato o ubicación diferente del controlador, las aplicaciones normalmente deben iniciar y apagar el servidor de objetos varias veces con el fin de prime sus cachés de datos durante la creación de objetos, es decir, Insertar objeto, Insertar objeto de archivo y pegar objeto.

Las versiones extendidas de estas funciones de creación resuelven este problema. OleCreateEx, OleCreateFromFileEx, OleCreateFromDataEx, OleCreateLinkEx, OleCreateLinkToFileEx y OleCreateLinkFromDataEx contienen los siguientes parámetros nuevos: dwFlags para indicar opciones adicionales, cFormats para indicar cuántos formatos se van a almacenar en caché, rgAdvf, de la enumeración ADVF , para especificar las marcas de asesoramiento para cada formato que se va a almacenar en caché, pAdviseSink para indicar si se requiere el almacenamiento en caché de presentación (controlador predeterminado) o de datos (no controlador predeterminado), rgdwConnection para devolver las cookies IDataObject::D Advise y pFormatEtc, una matriz de formatos en lugar de un solo formato.

Los contenedores que requieren que varias presentaciones se almacenen en caché en su nombre por el controlador del objeto simplemente pueden llamar a estas funciones y especificar el número de formatos en cFormats, las marcas de ADVF para cada formato en rgAdvf y el conjunto de formatos en pFormatEtc. Estos contenedores pasan NULL para pAdviseSink.

Los contenedores que realizan todos sus propios datos o almacenamiento en caché de presentaciones realizan estos mismos pasos, pero pasan un valor pAdviseSink que no seaNULL. Realizan su propio almacenamiento en caché o manipulación del objeto o los datos durante IAdviseSink::OnDataChange. Normalmente, estos contenedores nunca establecen las conexiones de asesoramiento con ADVF_NODATA, aunque no se les impide hacerlo.

Estas nuevas funciones son para documentos compuestos OLE. Con estas funciones, las aplicaciones pueden evitar los pasos de inicio e inicialización repetidos que requieren las funciones actuales. Están destinadas a aplicaciones contenedoras de documentos compuestos OLE que usan el almacenamiento en caché de presentación y datos predeterminados, y también en las aplicaciones que proporcionan su propio almacenamiento en caché y transferencia de datos desde la compatibilidad subyacente con IDataObject::D Advise .

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	ole2.h
Library	Ole32.lib
Archivo DLL	Ole32.dll