Classe COleDataObject

Usado em transferências de dados para recuperar dados em vários formatos da Área de Transferência, por meio de arrastar e soltar ou de um item OLE inserido.

Sintaxe

class COleDataObject

Membros

Construtores públicos

Nome	Descrição
COleDataObject::COleDataObject	Constrói um objeto COleDataObject.

Métodos públicos

Nome	Descrição
COleDataObject::Attach	Anexa o objeto de dados OLE especificado ao COleDataObject.
COleDataObject::AttachClipboard	Anexa o objeto de dados que está na área de transferência.
COleDataObject::BeginEnumFormats	Prepara-se para uma ou mais chamadas GetNextFormat subsequentes.
COleDataObject::Detach	Desanexa o objeto IDataObject associado.
COleDataObject::GetData	Copia dados do objeto de dados OLE anexado em um formato especificado.
COleDataObject::GetFileData	Copia dados do objeto de dados OLE anexado em um ponteiro CFile no formato especificado.
COleDataObject::GetGlobalData	Copia dados do objeto de dados OLE anexado em um HGLOBAL no formato especificado.
COleDataObject::GetNextFormat	Retorna o próximo formato de dados disponível.
COleDataObject::IsDataAvailable	Verifica se os dados estão disponíveis em um formato especificado.
COleDataObject::Release	Desanexa e libera o objeto IDataObject.

Comentários

COleDataObject não tem uma classe base.

Esses tipos de transferências de dados incluem uma origem e um destino. A fonte de dados é implementada como um objeto da classe COleDataSource. Sempre que um aplicativo de destino tiver dados descartados nele ou for solicitado a executar uma operação de colagem da Área de Transferência, um objeto da classe COleDataObject deve ser criado.

Essa classe permite que você determine se os dados existem em um formato especificado. Você também pode enumerar os formatos de dados disponíveis ou verificar se um determinado formato está disponível e, em seguida, recuperar os dados no formato preferencial. A recuperação de objeto pode ser realizada de várias formas diferentes, incluindo o uso de um CFile, um HGLOBAL ou uma estrutura STGMEDIUM.

Para mais informações, confira a estrutura STGMEDIUM no SDK do Windows.

Para obter mais informações sobre como usar objetos de dados no seu aplicativo, confira o artigo Objetos de Dados e Fontes de Dados (OLE).

Hierarquia de herança

COleDataObject

Requisitos

Cabeçalho: afxole.h

COleDataObject::Attach

Chame essa função para associar o objeto COleDataObject a um objeto de dados OLE.

void Attach(
    LPDATAOBJECT lpDataObject,
    BOOL bAutoRelease = TRUE);

Parâmetros

lpDataObject
Aponta para um objeto de dados OLE.

bAutoRelease
TRUE se o objeto de dados OLE deve ser liberado quando o objeto COleDataObject é destruído; caso contrário, FALSE.

Comentários

Para obter mais informações, confira IDataObject no SDK do Windows.

COleDataObject::AttachClipboard

Chame essa função para anexar o objeto de dados que está atualmente na Área de Transferência ao objeto COleDataObject.

BOOL AttachClipboard();

Valor de retorno

Diferente de zero se tiver êxito; caso contrário, 0.

Comentários

Observação

Chamar essa função bloqueia a Área de Transferência até que esse objeto de dados seja liberado. O objeto de dados é liberado no destruidor do COleDataObject. Para obter mais informações, consulte OpenClipboard e CloseClipboard na documentação do Win32.

COleDataObject::BeginEnumFormats

Chame essa função para se preparar para chamadas subsequentes para GetNextFormat a fim de recuperar uma lista de formatos de dados do item.

void BeginEnumFormats();

Comentários

Após uma chamada para BeginEnumFormats, a posição do primeiro formato compatível com esse objeto de dados é armazenada. As chamadas sucessivas para GetNextFormat enumerarão a lista de formatos disponíveis no objeto de dados.

Para verificar a disponibilidade de dados em um determinado formato, use COleDataObject::IsDataAvailable.

Para obter mais informações, confira IDataObject::EnumFormatEtc no SDK do Windows.

COleDataObject::COleDataObject

Constrói um objeto COleDataObject.

COleDataObject();

Comentários

Uma chamada para COleDataObject::Attach ou COleDataObject::AttachClipboard deve ser feita antes de chamar outras funções COleDataObject.

Observação

Como um dos parâmetros para os manipuladores do tipo "arrastar e soltar" é um ponteiro para um COleDataObject, não é necessário chamar esse construtor para dar suporte a arrastar e soltar.

COleDataObject::Detach

Chame essa função para desanexar o objeto COleDataObject do objeto de dados OLE associado sem liberar o objeto de dados.

LPDATAOBJECT Detach();

Valor de retorno

Um ponteiro para o objeto de dados OLE que foi desanexado.

Comentários

COleDataObject::GetData

Chame essa função para recuperar dados do item no formato especificado.

BOOL GetData(
    CLIPFORMAT cfFormat,
    LPSTGMEDIUM lpStgMedium,
    LPFORMATETC lpFormatEtc = NULL);

Parâmetros

cfFormat
O formato no qual os dados devem ser retornados. Esse parâmetro pode ser um dos formatos predefinidos da área de transferência ou o valor retornado pela função nativa RegisterClipboardFormat do Windows.

lpStgMedium
Aponta para uma estrutura STGMEDIUM que receberá dados.

lpFormatEtc
Aponta para uma estrutura FORMATETC que descreve o formato no qual os dados devem ser retornados. Forneça um valor para esse parâmetro se você quiser especificar informações de formato adicionais além do formato de área de transferência especificado pelo cfFormat. Se for NULL, os valores padrão serão usados para os outros campos na estrutura FORMATETC.

Valor de retorno

Diferente de zero se tiver êxito; caso contrário, 0.

Comentários

Para obter mais informações, confira IDataObject::GetData, STGMEDIUM e FORMATETC no SDK do Windows.

Para obter mais informações, confira RegisterClipboardFormat no SDK do Windows.

COleDataObject::GetFileData

Chame essa função para criar um objeto derivado de CFile ou CFile e para recuperar dados no formato especificado em um ponteiro CFile.

CFile* GetFileData(
    CLIPFORMAT cfFormat,
    LPFORMATETC lpFormatEtc = NULL);

Parâmetros

cfFormat
O formato no qual os dados devem ser retornados. Esse parâmetro pode ser um dos formatos predefinidos da área de transferência ou o valor retornado pela função nativa RegisterClipboardFormat do Windows.

lpFormatEtc
Aponta para uma estrutura FORMATETC que descreve o formato no qual os dados devem ser retornados. Forneça um valor para esse parâmetro se você quiser especificar informações de formato adicionais além do formato de área de transferência especificado pelo cfFormat. Se for NULL, os valores padrão serão usados para os outros campos na estrutura FORMATETC.

Valor de retorno

Ponteiro para o novo objeto derivado de CFile ou CFile que contém os dados se tiver êxito. Caso contrário, NULL.

Comentários

Dependendo do meio em que os dados são armazenados, o tipo real apontado pelo valor retornado pode ser CFile, CSharedFile ou COleStreamFile.

Observação

O objeto CFile acessado pelo valor retornado dessa função pertence ao chamador. É responsabilidade do chamador delete o objeto CFile, portanto, fechando o arquivo.

Para obter mais informações, confira FORMATETC no SDK do Windows.

Para obter mais informações, confira RegisterClipboardFormat no SDK do Windows.

COleDataObject::GetGlobalData

Chame essa função para alocar um bloco de memória global e recuperar dados no formato especificado em um HGLOBAL.

HGLOBAL GetGlobalData(
    CLIPFORMAT cfFormat,
    LPFORMATETC lpFormatEtc = NULL);

Parâmetros

cfFormat
O formato no qual os dados devem ser retornados. Esse parâmetro pode ser um dos formatos predefinidos da área de transferência ou o valor retornado pela função nativa RegisterClipboardFormat do Windows.

lpFormatEtc
Aponta para uma estrutura FORMATETC que descreve o formato no qual os dados devem ser retornados. Forneça um valor para esse parâmetro se você quiser especificar informações de formato adicionais além do formato de área de transferência especificado pelo cfFormat. Se for NULL, os valores padrão serão usados para os outros campos na estrutura FORMATETC.

Valor de retorno

O identificador do bloco de memória global que contém os dados, se bem-sucedido. Caso contrário, NULL.

Comentários

Para obter mais informações, confira FORMATETC no SDK do Windows.

Para obter mais informações, confira RegisterClipboardFormat no SDK do Windows.

COleDataObject::GetNextFormat

Chame essa função repetidamente a fim de obter todos os formatos disponíveis para recuperar dados do item.

BOOL GetNextFormat(LPFORMATETC lpFormatEtc);

Parâmetros

lpFormatEtc
Aponta para a estrutura FORMATETC que recebe as informações de formato quando a chamada de função retorna.

Valor de retorno

Não zero se outro formato estiver disponível. Caso contrário, 0.

Comentários

Após uma chamada para COleDataObject::BeginEnumFormats, a posição do primeiro formato compatível com esse objeto de dados será armazenada. As chamadas sucessivas para GetNextFormat enumerarão a lista de formatos disponíveis no objeto de dados. Use essas funções para listar os formatos disponíveis.

Para verificar a disponibilidade de um determinado formato, chame COleDataObject::IsDataAvailable.

Para obter mais informações, confira IEnumXXXX::Next no SDK do Windows.

COleDataObject::IsDataAvailable

Chame essa função para determinar se um formato específico está disponível para recuperar dados do item OLE.

BOOL IsDataAvailable(
    CLIPFORMAT cfFormat,
    LPFORMATETC lpFormatEtc = NULL);

Parâmetros

cfFormat
O formato de dados da área de transferência a ser usado na estrutura apontada por lpFormatEtc. Esse parâmetro pode ser um dos formatos predefinidos da área de transferência ou o valor retornado pela função nativa RegisterClipboardFormat do Windows.

lpFormatEtc
Aponta para uma estrutura FORMATETC que descreve o formato desejado. Forneça um valor para esse parâmetro somente se você quiser especificar informações de formato adicionais além do formato de área de transferência especificado por cfFormat. Se for NULL, os valores padrão serão usados para os outros campos na estrutura FORMATETC.

Valor de retorno

Não zero se os dados estiverem disponíveis no formato especificado; caso contrário, 0.

Comentários

Essa função é útil antes de chamar GetData, GetFileDataou GetGlobalData.

Para obter mais informações, confira IDataObject::QueryGetData e FORMATETC no SDK do Windows.

Para obter mais informações, confira RegisterClipboardFormat no SDK do Windows.

Exemplo

Confira o exemplo para CRichEditView::QueryAcceptData.

COleDataObject::Release

Chame essa função para liberar a propriedade do objeto IDataObject que anteriormente estava associado ao objeto COleDataObject.

void Release();

Comentários

O IDataObject foi associado ao COleDataObject através da chamada explícita de Attach ou AttachClipboard ou pela estrutura. Se o parâmetro bAutoRelease de Attach for FALSE, o objeto IDataObject não será liberado. Nesse caso, o chamador é responsável por liberar o IDataObject chamando IUnknown::Release.

Confira também

HIERSVR de exemplo do MFC
OCLIENT de exemplo do MFC
Gráfico da hierarquia
Classe COleDataSource
Classe COleClientItem
Classe COleServerItem