Función OleCreateLinkFromDataEx (ole2.h)

Amplía la funcionalidad OleCreateLinkFromData al admitir instancias más eficaces de objetos en contenedores que requieren almacenamiento en caché de varios formatos de presentaciones o datos, en lugar del formato único admitido por OleCreateLinkFromData.

Sintaxis

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

Parámetros

[in] pSrcDataObj

Puntero al objeto de datos desde el que se va a crear un objeto de vínculo.

[in] riid

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

[in] dwFlags

Este parámetro 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 es OLERENDER_FORMAT, apunta a una matriz de elementos DWORD , 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 es OLERENDER_FORMAT, apunta a una matriz de estructuras FORMATETC . 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 memoria 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.

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

[in, 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. Este parámetro debe ser NULL si pAdviseSink es NULL.

[in] pClientSite

Puntero a la interfaz principal a través de la cual el objeto solicitará servicios desde 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 almacenamiento en caché de presentación o datos predeterminados establecido para él.

[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 incluyen lo siguiente.

Comentarios

La siguiente llamada a OleCreateLinkFromData:

OleCreateLinkFromData(pSrcDataObj, riid, renderopt, pFormatEtc, pClientSite, pStg, ppvObj);

equivale a la siguiente llamada a OleCreateLinkFromDataEx:

DWORD    advf = ADVF_PRIMEFIRST;
    OleCreateLinkFromDataEx(pSrcDataObj, riid, renderopt, 1, &advf, pFormatEtc, NULL, NULL, pClientSite, pStg, ppvObj);

Las funciones de creación de instancias existentes (OleCreate,OleCreateFromFile, OleCreateFromData, OleCreateLink, OleCreateLinkToFile y OleCreateLinkFromData), crean solo una memoria caché de formato de presentación o 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 el 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 para primor sus cachés de datos durante la creación de objetos, es decir, Insertar objeto, Insertar objeto desde 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 aviso 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 predeterminado), rgdwConnection para devolver las cookies IDataObject::D Advise y rgFormatEtc, 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 rgFormatEtc. Estos contenedores pasan NULL para pAdviseSink.

Los contenedores que realizan todos sus propios datos o almacenamiento en caché de presentación realizan estos mismos pasos, pero pasan un pAdviseSink que no sea NULL. 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. Se dirigen a aplicaciones de contenedor de documentos compuestos OLE que usan el almacenamiento en caché de presentación y datos predeterminados, así como en las aplicaciones que proporcionan su propio almacenamiento en caché y transferencia de datos desde la compatibilidad subyacente con IDataObject::D Advise .

Requisitos

Consulte también

IAdviseSink::OnDataChange

IDataObject::D Advise

IOleCache::Cache

IOleObject::SetClientSite

OleCreate

OleCreateLinkFromData