ClipboardObject.IDataObject.GetCanonicalFormatEtc Method

Article
10/02/2013

Provides a standard FORMATETC structure that is logically equivalent to a more complex structure. Use this method to determine whether two different FORMATETC structures return the same data, removing the need for duplicate rendering.

Namespace: Microsoft.VisualStudio.Data.Framework
Assembly: Microsoft.VisualStudio.Data.Framework (in Microsoft.VisualStudio.Data.Framework.dll)

Syntax

'Declaration
Private Function GetCanonicalFormatEtc ( _
    pformatectIn As FORMATETC(), _
    pformatetcOut As FORMATETC() _
) As Integer Implements IDataObject.GetCanonicalFormatEtc

int IDataObject.GetCanonicalFormatEtc(
    FORMATETC[] pformatectIn,
    FORMATETC[] pformatetcOut
)

private:
virtual int GetCanonicalFormatEtc(
    array<FORMATETC>^ pformatectIn, 
    array<FORMATETC>^ pformatetcOut
) sealed = IDataObject::GetCanonicalFormatEtc

private abstract GetCanonicalFormatEtc : 
        pformatectIn:FORMATETC[] * 
        pformatetcOut:FORMATETC[] -> int  
private override GetCanonicalFormatEtc : 
        pformatectIn:FORMATETC[] * 
        pformatetcOut:FORMATETC[] -> int

JScript does not support explicit interface implementations.

Parameters

pformatectIn
Type: array<Microsoft.VisualStudio.OLE.Interop.FORMATETC[]

A reference to a FORMATETC structure, passed by reference, that defines the format, medium, and target device that the caller would like to use to retrieve data in a subsequent call, such as IDataObject.GetData. The tymed member is not significant in this case and should be ignored.

pformatetcOut
Type: array<Microsoft.VisualStudio.OLE.Interop.FORMATETC[]

When this method returns, contains a pointer to a FORMATETC structure that contains the most general information possible for a specific rendering, making it canonically equivalent to pformatectIn. The caller must allocate this structure and the GetCanonicalFormatEtc method must fill in the data. To retrieve data in a subsequent call, such as IDataObject.GetData, the caller uses the supplied value of pformatetcOut, unless the value supplied is nulla null reference (Nothing in Visual Basic). This value is null if the method returns DATA_S_SAMEFORMATETC. The tymed member is not significant in this case and should be ignored. This parameter is passed uninitialized.

Return Value

Type: System.Int32
This method supports the standard return values E_INVALIDARG, E_FAIL, E_UNEXPECTED, and E_OUTOFMEMORY, as well as the following:

Value	Description
S_OK	The returned FORMATETC structure is different from the one that was passed.
DATA_S_SAMEFORMATETC	The FORMATETC structures are the same and a null reference is returned in the pformatetcOut parameter.
DV_E_LINDEX	There is an invalid value for lindex; currently, only -1 is supported.
DV_E_FORMATETC	There is an invalid value for the pformatectIn parameter.
OLE_E_NOTRUNNING	The application is not running.

Implements

IDataObject.GetCanonicalFormatEtc(array<FORMATETC[], array<FORMATETC[])

Remarks

If the clipboard object wraps an existing IDataObject (from the Microsoft.VisualStudio.OLE.Interop namespace), this method delegates the call to the corresponding GetCanonicalFormatEtc from that namespace. Otherwise, it attempts to translate the call to GetCanonicalFormatEtc from the System.Runtime.InteropServices.ComTypes namespace, in case the clipboard object could be wrapping an existing IDataObject.

.NET Framework Security

Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see Using Libraries from Partially Trusted Code.

Share via