Formatos da área de transferência do Shell
Os formatos da área de transferência do Shell são usados para identificar o tipo de dados do Shell que estão sendo transferidos por meio da área de transferência. A maioria dos formatos de área de transferência do Shell identifica um tipo de dados, como uma lista de nomes de arquivo ou ponteiros para PIDLs (listas de identificadores de item). No entanto, alguns formatos são usados para comunicação entre a origem e o destino. Eles podem agilizar o processo de transferência de dados dando suporte a operações do Shell, como movimentação otimizada e delete_on_paste. Os dados do Shell estão sempre contidos em um objeto de dados que usa uma estrutura FORMATETC como uma maneira mais geral de caracterizar dados. O membro cfFormat da estrutura é definido como o formato da área de transferência para o item específico de dados. Os outros membros fornecem informações adicionais, como o mecanismo de transferência de dados. Os dados estão contidos em uma estrutura STGMEDIUM que acompanha.
Observação
Os identificadores de formato de área de transferência padrão têm o formulário CF_XXX. Um exemplo comum é CF_TEXT, que é usado para transferir dados de texto ANSI. Esses identificadores têm valores predefinidos e podem ser usados diretamente com estruturas FORMATETC . Com exceção de CF_HDROP, os identificadores de formato shell não são predefinidos. Com exceção de DragWindow, eles têm o formulário CFSTR_XXX. Para diferenciar esses valores de formatos predefinidos, eles geralmente são chamados de formatos simples. No entanto, ao contrário dos formatos predefinidos, eles devem ser registrados pela origem e pelo destino antes de poderem ser usados para transferir dados. Para registrar um formato shell, inclua o arquivo de cabeçalho Shlobj.h e passe o identificador de formato CFSTR_XXX para RegisterClipboardFormat. Essa função retorna um valor de formato de área de transferência válido, que pode ser usado como o membro cfFormat de uma estrutura FORMATETC .
Os formatos da área de transferência do Shell são organizados aqui em três grupos, com base em como eles são usados.
- Formatos para transferir objetos do sistema de arquivos
- Formatos para transferir objetos virtuais
- Formatos de comunicação entre a origem e o destino
Esses formatos são usados para transferir um ou mais arquivos ou outros objetos Shell.
- CF_HDROP
- CFSTR_FILECONTENTS
- CFSTR_FILEDESCRIPTOR
- CFSTR_FILENAME
- CFSTR_FILENAMEMAP
- CFSTR_MOUNTEDVOLUME
- CFSTR_SHELLIDLIST
- CFSTR_SHELLIDLISTOFFSET
Esse formato de área de transferência é usado ao transferir os locais de um grupo de arquivos existentes. Ao contrário dos outros formatos do Shell, ele é predefinido, portanto, não é necessário chamar RegisterClipboardFormat. Os dados consistem em uma estrutura STGMEDIUM que contém um objeto de memória global. O membro hGlobal da estrutura aponta para uma estrutura DROPFILES como seu membro hGlobal .
O membro pFiles da estrutura DROPFILES contém um deslocamento para uma matriz de caracteres terminada em nulo duplo que contém os nomes de arquivo. Se você estiver extraindo um formato CF_HDROP de um objeto de dados, poderá usar DragQueryFile para extrair nomes de arquivo individuais do objeto de memória global. Se você estiver criando um formato CF_HDROP para colocar em um objeto de dados, precisará construir a matriz de nomes de arquivo.
A matriz de nomes de arquivo consiste em uma série de cadeias de caracteres, cada uma contendo o caminho totalmente qualificado de um arquivo, incluindo o caractere NULL de terminação. Um caractere nulo adicional é acrescentado à cadeia de caracteres final para encerrar a matriz. Por exemplo, se os arquivos c:\temp1.txt e c:\temp2.txt estiverem sendo transferidos, a matriz de caracteres terá esta aparência:
c:\temp1.txt'\0'c:\temp2.txt'\0''\0'
Observação
Neste exemplo, '\0' é usado para representar o caractere nulo , não os caracteres literais que devem ser incluídos.
Se o objeto tiver sido copiado para a área de transferência como parte de uma operação de arrastar e soltar, o membro pt da estrutura DROPFILES conterá as coordenadas do ponto em que o objeto foi descartado. Você pode usar DragQueryPoint para extrair as coordenadas do cursor.
Se esse formato estiver presente em um objeto de dados, um loop de arrastar OLE simula WM_DROPFILES funcionalidade com destinos de soltar não OLE. Isso é importante se o aplicativo for a origem de uma operação de arrastar e soltar em um sistema Windows 3.1.
Esse identificador de formato é usado com o formato CFSTR_FILEDESCRIPTOR para transferir dados como se fossem um arquivo, independentemente de como eles são realmente armazenados. Os dados consistem em uma estrutura STGMEDIUM que representa o conteúdo de um arquivo. O arquivo normalmente é representado como um objeto de fluxo, o que evita a necessidade de colocar o conteúdo do arquivo na memória. Nesse caso, o membro tymed da estrutura STGMEDIUM é definido como TYMED_ISTREAM e o arquivo é representado por uma interface IStream . O arquivo também pode ser um objeto de memória global ou de armazenamento (TYMED_ISTORAGE ou TYMED_HGLOBAL). O formato de CFSTR_FILEDESCRIPTOR associado contém uma estrutura FILEESCRIPTOR para cada arquivo que especifica o nome e os atributos do arquivo.
O destino trata os dados associados a um formato CFSTR_FILECONTENTS como se fossem um arquivo. Quando o destino chama IDataObject::GetData para extrair os dados, ele especifica um arquivo específico definindo o membro lindex da estrutura FORMATETC como o índice baseado em zero da estrutura FILEESCRIPTOR do arquivo no formato de CFSTR_FILEDESCRIPTOR . Em seguida, o destino usa o ponteiro de interface retornado ou o identificador de memória global para extrair os dados.
Esse identificador de formato é usado com o formato CFSTR_FILECONTENTS para transferir dados como um grupo de arquivos. Esses dois formatos são a maneira preferencial de transferir objetos Shell que não são armazenados como arquivos do sistema de arquivos. Por exemplo, esses formatos podem ser usados para transferir um grupo de mensagens de email como arquivos individuais, mesmo que cada email seja realmente armazenado como um bloco de dados em um banco de dados. Os dados consistem em uma estrutura STGMEDIUM que contém um objeto de memória global. O membro hGlobal da estrutura aponta para uma estrutura FILEGROUPDESCRIPTOR seguida por uma matriz que contém uma estrutura FILEESCRIPTOR para cada arquivo no grupo. Para cada estrutura FILEESCRIPTOR , há um formato de CFSTR_FILECONTENTS separado que contém o conteúdo do arquivo. Para identificar o formato CFSTR_FILECONTENTS de um arquivo específico, defina o valor lIndex da estrutura FORMATETC para o índice baseado em zero da estrutura FILEESCRIPTOR do arquivo.
O formato CFSTR_FILEDESCRIPTOR normalmente é usado para transferir dados como se fossem um grupo de arquivos, independentemente de como eles são realmente armazenados. Da perspectiva do destino, cada formato CFSTR_FILECONTENTS representa um único arquivo e é tratado adequadamente. No entanto, a origem pode armazenar os dados da maneira que quiser. Embora um formato de CSFTR_FILECONTENTS possa corresponder a um único arquivo, ele também pode, por exemplo, representar dados extraídos pela origem de um banco de dados ou documento de texto.
Esse identificador de formato é usado para transferir um único arquivo. Os dados consistem em uma estrutura STGMEDIUM que contém um objeto de memória global. O membro hGlobal da estrutura aponta para uma única cadeia de caracteres terminada em nulo que contém o caminho de arquivo totalmente qualificado do arquivo. Esse formato foi substituído por CF_HDROP, mas tem suporte para compatibilidade com versões anteriores com aplicativos do Windows 3.1.
Esse identificador de formato é usado quando um grupo de arquivos no formato CF_HDROP está sendo renomeado, bem como transferido. Os dados consistem em uma estrutura STGMEDIUM que contém um objeto de memória global. O membro hGlobal da estrutura aponta para uma matriz de caracteres terminada em nulo duplo. Essa matriz contém um novo nome para cada arquivo, na mesma ordem em que os arquivos são listados no formato de CF_HDROP. O formato da matriz de caracteres é o mesmo usado por CF_HDROP para listar os arquivos transferidos.
Esse identificador de formato é usado para transferir um caminho em um volume montado. Ele é semelhante a CF_HDROP, mas contém apenas um único caminho e pode lidar com as cadeias de caracteres de caminho mais longas que podem ser necessárias para representar um caminho quando o volume é montado em uma pasta. Os dados consistem em uma estrutura STGMEDIUM que contém um objeto de memória global. O membro hGlobal da estrutura aponta para uma única cadeia de caracteres terminada em nulo que contém o caminho do arquivo totalmente qualificado. A cadeia de caracteres de caminho deve terminar com um caractere '\', seguido pelo NULL de terminação.
Antes do Windows 2000, os volumes podiam ser montados apenas em letras de unidade. Para sistemas Windows 2000 e posteriores com uma unidade formatada em NTFS, você também pode montar volumes em pastas vazias. Esse recurso permite que um volume seja montado sem usar uma letra de unidade. O volume montado pode usar qualquer formato com suporte no momento, incluindo FAT, FAT32, NTFS e CDFS.
Você pode adicionar páginas a uma folha de propriedades propriedades da unidade implementando um manipulador de folha de propriedades. Se o volume estiver montado em uma letra de unidade, o Shell passará informações de caminho para o manipulador com o formato CF_HDROP . Com o Windows 2000 e sistemas posteriores, o formato CF_HDROP é usado quando um volume é montado em uma letra de unidade, assim como acontece com sistemas anteriores. No entanto, se um volume for montado em uma pasta, o identificador de formato CFSTR_MOUNTEDVOLUME será usado em vez de CF_HDROP.
Se apenas letras de unidade forem usadas para montar volumes, somente CF_HDROP serão usados e os manipuladores de folha de propriedades existentes funcionarão como fizeram com sistemas anteriores. No entanto, se você quiser que seu manipulador exiba uma página para volumes montados em pastas, bem como letras de unidade, o manipulador deve ser capaz de entender os formatos CSFTR_MOUNTEDVOLUME e CF_HDROP.
Esse identificador de formato é usado ao transferir os locais de um ou mais objetos de namespace existentes. Ele é usado da mesma maneira que CF_HDROP, mas contém PIDLs em vez de caminhos do sistema de arquivos. O uso de PIDLs permite que o formato CFSTR_SHELLIDLIST manipule objetos virtuais, bem como objetos do sistema de arquivos. Os dados são uma estrutura STGMEDIUM que contém um objeto de memória global. O membro hGlobal da estrutura aponta para uma estrutura CIDA .
O membro aoffset da estrutura CIDA é uma matriz que contém deslocamentos para o início da estrutura ITEMIDLIST para cada PIDL que está sendo transferido. Para extrair um PIDL específico, primeiro determine seu índice. Em seguida, adicione o valor aoffset que corresponde a esse índice ao endereço da estrutura CIDA .
O primeiro elemento de aoffset contém um deslocamento para o PIDL totalmente qualificado de uma pasta pai. Se esse PIDL estiver vazio, a pasta pai será a área de trabalho. Cada um dos elementos restantes da matriz contém um deslocamento para um dos PIDLs a serem transferidos. Todos esses PIDLs são relativos ao PIDL da pasta pai.
As duas macros a seguir podem ser usadas para recuperar PIDLs de uma estrutura CIDA . O primeiro usa um ponteiro para a estrutura e recupera o PIDL da pasta pai. O segundo usa um ponteiro para a estrutura e recupera um dos outros PIDLs, identificados por seu índice baseado em zero.
#define GetPIDLFolder(pida) (LPCITEMIDLIST)(((LPBYTE)pida)+(pida)->aoffset[0])
#define GetPIDLItem(pida, i) (LPCITEMIDLIST)(((LPBYTE)pida)+(pida)->aoffset[i+1])
Observação
O valor retornado por essas macros é um ponteiro para a estrutura ITEMIDLIST do PIDL. Como essas estruturas variam de comprimento, você deve determinar o fim da estrutura percorrendo cada uma das estruturas SHITEMID da estrutura ITEMIDLIST até atingir o NULL de dois bytes que marca o final.
Esse identificador de formato é usado com formatos como CF_HDROP, CFSTR_SHELLIDLIST e CFSTR_FILECONTENTS para especificar a posição de um grupo de objetos após uma transferência. Os dados consistem em uma estrutura STGMEDIUM que contém um objeto de memória global. O membro hGlobal da estrutura aponta para uma matriz de estruturas POINT . A primeira estrutura especifica as coordenadas da tela, em pixels, do canto superior esquerdo do retângulo que envolve o grupo. O restante das estruturas especifica os locais dos objetos individuais em relação à posição do grupo. Eles devem estar na mesma ordem usada para listar os objetos no formato associado.
O formato CFSTR_SHELLIDLIST pode ser usado para transferir o sistema de arquivos e objetos virtuais. No entanto, também há vários formatos especializados para transferir tipos específicos de objetos virtuais.
Esse identificador de formato é usado ao transferir recursos de rede, como um domínio ou servidor. Os dados são uma estrutura STGMEDIUM que contém um objeto de memória global. O membro hGlobal da estrutura aponta para uma estrutura NRESARRAY . O membro nr dessa estrutura indica uma estrutura NETRESOURCE cujo membro lpRemoteName contém uma cadeia de caracteres terminada em nulo que identifica o recurso de rede. Em seguida, o destino de remoção pode usar os dados com qualquer uma das funções de API de Rede do Windows (WNet ), como WNetAddConnection, para executar operações de rede no objeto .
Esse identificador de formato é usado ao transferir os nomes amigáveis das impressoras. Os dados são uma estrutura STGMEDIUM que contém um objeto de memória global. O membro hGlobal da estrutura aponta para uma cadeia de caracteres no mesmo formato que o usado com CF_HDROP. No entanto, o membro pFiles da estrutura DROPFILES contém um ou mais nomes amigáveis de impressoras em vez de caminhos de arquivo.
Esse identificador de formato substitui CFSTR_SHELLURL (preterido). Se você quiser que seu aplicativo manipule URLs da área de transferência, use CFSTR_INETURL em vez de CFSTR_SHELLURL (preterido). Esse formato fornece a melhor representação da área de transferência de uma única URL. Se UNICODE não estiver definido, o aplicativo recuperará a versão CF_TEXT/CFSTR_SHELLURL da URL. Se UNICODE for definido, o aplicativo recuperará a versão CF_UNICODE da URL.
Observação
Esse identificador de formato foi preterido; use CFSTR_INETURL em vez disso.
Esses identificadores de formato permitem a comunicação entre a origem e o destino. Os formatos acompanham os dados e dão aos aplicativos um maior grau de controle sobre operações move-copy-paste ou drag-and-drop envolvendo objetos Shell.
- CFSTR_INDRAGLOOP
- CFSTR_LOGICALPERFORMEDDROPEFFECT
- CFSTR_PASTESUCCEEDED
- CFSTR_PERFORMEDDROPEFFECT
- CFSTR_PREFERREDDROPEFFECT
- CFSTR_TARGETCLSID
- CFSTR_UNTRUSTEDDRAGDROP
- DragWindow
Esse identificador de formato é usado por um objeto de dados para indicar se ele está em um loop de arrastar e soltar. Os dados são uma estrutura STGMEDIUM que contém um objeto de memória global. O membro hGlobal da estrutura aponta para um valor DWORD . Se o valor DWORD não for zero, o objeto de dados estará dentro de um loop de arrastar e soltar. Se o valor for definido como zero, o objeto de dados não estará dentro de um loop de arrastar e soltar.
Alguns destinos de soltar podem chamar IDataObject::GetData e tentar extrair dados enquanto o objeto ainda está dentro do loop de arrastar e soltar. Renderizar totalmente o objeto para cada ocorrência desse tipo pode fazer com que o cursor de arrastar parasse. Se o objeto de dados der suporte a CFSTR_INDRAGLOOP, o destino poderá usar esse formato para marcar o status do loop de arrastar e soltar e evitar a renderização intensiva de memória do objeto até que ele seja realmente descartado. Os formatos que têm uso intensivo de memória para renderizar ainda devem ser incluídos no enumerador FORMATETC e em chamadas para IDataObject::QueryGetData. Se o objeto de dados não definir CFSTR_INDRAGLOOP, ele deverá agir como se o valor fosse definido como zero.
Versão 5.0. Esse identificador de formato permite que uma fonte de descarte chame o método IDataObject::GetData do objeto de dados para determinar o resultado de uma transferência de dados do Shell. Os dados são uma estrutura STGMEDIUM que contém um objeto de memória global. O membro hGlobal da estrutura aponta para um DWORD que contém um valor DROPEFFECT .
O identificador de formato CFSTR_PERFORMEDDROPEFFECT foi destinado a permitir que o destino indicasse ao objeto de dados qual operação realmente ocorreu. No entanto, o Shell usa movimentações otimizadas para objetos do sistema de arquivos sempre que possível. Nesse caso, o Shell normalmente define o valor CFSTR_PERFORMEDDROPEFFECT como DROPEFFECT_NONE, para indicar ao objeto de dados que os dados originais foram excluídos. Portanto, a origem não pode usar o valor CFSTR_PERFORMEDDROPEFFECT para determinar qual operação ocorreu. Embora a maioria das fontes não precise dessas informações, há algumas exceções. Por exemplo, embora os movimentos otimizados eliminem a necessidade de uma fonte excluir quaisquer dados, a fonte ainda pode precisar atualizar um banco de dados relacionado para indicar que os arquivos foram movidos ou copiados.
Se uma fonte precisar saber qual operação ocorreu, ela poderá chamar o método IDataObject::GetData do objeto de dados e solicitar o formato CFSTR_LOGICALPERFORMEDDROPEFFECT. Esse formato reflete essencialmente o que acontece do ponto de vista do usuário após a conclusão da operação. Se um novo arquivo for criado e o arquivo original for excluído, o usuário verá uma operação de movimentação e o valor de dados do formato será definido como DROPEFFECT_MOVE. Se o arquivo original ainda estiver lá, o usuário verá uma operação de cópia e o valor de dados do formato será definido como DROPEFFECT_COPY. Se um link tiver sido criado, o valor de dados do formato será DROPEFFECT_LINK.
Esse identificador de formato é usado pelo destino para informar ao objeto de dados, por meio de seu método IDataObject::SetData , que uma operação delete-on-paste foi bem-sucedida. Os dados são uma estrutura STGMEDIUM que contém um objeto de memória global. O membro hGlobal da estrutura aponta para um DWORD que contém um valor DROPEFFECT . Esse formato é usado para notificar o objeto de dados de que ele deve concluir a operação de corte e excluir os dados originais, se necessário. Para obter mais informações, consulte Operações Delete-on-Paste.
Esse identificador de formato é usado pelo destino para informar o objeto de dados por meio do método IDataObject::SetData do resultado de uma transferência de dados. Os dados são uma estrutura STGMEDIUM que contém um objeto de memória global. O membro hGlobal da estrutura aponta para um DWORD definido como o valor DROPEFFECT apropriado, normalmente DROPEFFECT_MOVE ou DROPEFFECT_COPY.
Esse formato normalmente é usado quando o resultado de uma operação pode ser mover ou copiar, como em uma operação otimizada de movimentação ou exclusão ao colar. Ele fornece uma maneira confiável para o destino informar ao objeto de dados o que realmente aconteceu. Ele foi introduzido porque o valor de pdwEffect retornado por DoDragDrop não indicou de forma confiável qual operação havia ocorrido. O formato CFSTR_PERFORMEDDROPEFFECT é a maneira confiável de indicar que ocorreu um movimento não otimizado.
Esse identificador de formato é usado pela origem para especificar se seu método preferencial de transferência de dados é mover ou copiar. Um destino de soltar solicita esse formato chamando o método IDataObject::GetData do objeto de dados. Os dados são uma estrutura STGMEDIUM que contém um objeto de memória global. O membro hGlobal da estrutura aponta para um valor DWORD . Esse valor será definido como DROPEFFECT_MOVE se uma operação de movimentação for preferencial ou DROPEFFECT_COPY se uma operação de cópia for preferencial.
Esse recurso é usado quando uma origem pode dar suporte a uma operação de movimentação ou cópia. Ele usa o formato CFSTR_PREFERREDDROPEFFECT para comunicar sua preferência ao destino. Como o destino não é obrigado a honrar a solicitação, o destino deve chamar o método IDataObject::SetData da origem com um formato CFSTR_PERFORMEDDROPEFFECT para informar ao objeto de dados qual operação foi realmente executada.
Com uma operação delete-on-paste , o formato CFSTR_PREFERREDDROPFORMAT é usado para informar ao destino se a origem fez um corte ou cópia. Com uma operação de arrastar e soltar, você pode usar CFSTR_PREFERREDDROPFORMAT para especificar a ação do Shell. Se esse formato não estiver presente, o Shell executará uma ação padrão, com base no contexto. Por exemplo, se um usuário arrastar um arquivo de um volume e o soltar em outro volume, a ação padrão do Shell será copiar o arquivo. Ao incluir um formato de CFSTR_PREFERREDDROPFORMAT no objeto de dados, você pode substituir a ação padrão e instruir explicitamente o Shell a copiar, mover ou vincular o arquivo. Se o usuário optar por arrastar com o botão direito, CFSTR_PREFERREDDROPFORMAT especificará o comando padrão no menu de atalho arrastar e soltar . O usuário ainda está livre para escolher outros comandos no menu.
Antes do Microsoft Internet Explorer 4.0, um aplicativo indicava que estava transferindo tipos de arquivo de atalho definindo FD_LINKUI no membro dwFlags da estrutura FILEESCRIPTOR. Em seguida, os destinos tiveram que usar uma chamada potencialmente demorada para IDataObject::GetData para descobrir se o sinalizador FD_LINKUI foi definido. Agora, a maneira preferencial de indicar que os atalhos estão sendo transferidos é usar o formato CFSTR_PREFERREDDROPEFFECT definido como DROPEFFECT_LINK. No entanto, para compatibilidade com versões anteriores com sistemas mais antigos, as fontes ainda devem definir o sinalizador FD_LINKUI.
Esse identificador de formato é usado por um destino para fornecer seu CLSID à origem. Os dados são uma estrutura STGMEDIUM que contém um objeto de memória global. O membro hGlobal da estrutura aponta para o GUID CLSID do destino de soltar.
Esse formato é usado principalmente para permitir que objetos sejam excluídos arrastando-os para a Lixeira. Quando um objeto é descartado na Lixeira, o método IDataObject::SetData da origem é chamado com um formato CFSTR_TARGETCLSID definido como CLSID (CLSID_RecycleBin) da Lixeira. Em seguida, a origem pode excluir o objeto original.
Esse identificador de formato é usado pelo Windows Internet Explorer e pelo Shell do Windows para fornecer um mecanismo por meio do qual bloquear ou solicitar operações de arrastar e soltar provenientes da Internet Explorer em conjunto com o sinalizador URLACTION_SHELL_ENHANCED_DRAGDROP_SECURITY.
CFSTR_UNTRUSTEDDRAGDROP é adicionado pela origem de uma operação de arrastar e soltar para especificar que o objeto de dados pode conter dados não confiáveis. Os dados são representados por uma estrutura STGMEDIUM que contém um objeto de memória global. O membro hGlobal da estrutura aponta para um DWORD definido como um sinalizador de Ação de URL apropriado para causar um marcar de política por meio do método IInternetSecurityManager::P rocessUrlAction, usando o sinalizador PUAF_ENFORCERESTRICTED.
Esse formato é usado em uma operação de arrastar e soltar para identificar a imagem de arrastar (janela) de um objeto para que suas informações visuais possam ser atualizadas dinamicamente. Quando um objeto é arrastado sobre um destino de soltar, um aplicativo atualiza sua estrutura DROPDESCRIPTION em resposta ao método IDropTarget::D ragOver ou IDropSource::GiveFeedback . O DROPDESCRIPTION é atualizado com um novo valor DROPIMAGETYPE que indica a decoração a ser aplicada ao visual da janela de arrastar; por exemplo, uma indicação de que o arquivo está sendo copiado em vez de movido ou que o objeto não pode ser removido para esse local. No entanto, até que o objeto receba uma mensagem DDWM_UPDATEWINDOW , os visuais não serão atualizados. Esse formato fornece o HWND da janela de arrastar do destinatário para o remetente da mensagem DDWM_UPDATEWINDOW .
Os dados da área de transferência são do tipo TYMED_HGLOBAL. É uma representação DWORD de um HWND. Os dados podem ser passados para a função ULongToHandle , definida em Basetsd.h, para fornecer um HWND de 64 bits para uso no Windows de 64 bits.
Esse formato não requer a inclusão de Shlobj.h.