Compartir a través de

Formatos del Portapapeles de Shell

  • Artículo

Los formatos del Portapapeles de Shell se usan para identificar el tipo de datos de Shell que se transfieren a través del Portapapeles. La mayoría de los formatos del Portapapeles de Shell identifican un tipo de datos, como una lista de nombres de archivo o punteros a listas de identificadores de elementos (PIDL). Sin embargo, algunos formatos se usan para la comunicación entre el origen y el destino. Pueden acelerar el proceso de transferencia de datos si admiten operaciones de Shell, como el movimiento optimizado y la delete_on_paste. Los datos de Shell siempre están contenidos en un objeto de datos que usa una estructura FORMATETC como una manera más general de caracterizar los datos. El miembro cfFormat de la estructura se establece en el formato del Portapapeles para el elemento de datos concreto. Los demás miembros proporcionan información adicional, como el mecanismo de transferencia de datos. Los datos están contenidos en una estructura STGMEDIUM complementaria.

Nota

Los identificadores de formato estándar del Portapapeles tienen el formulario CF_XXX. Un ejemplo común es CF_TEXT, que se usa para transferir datos de texto ANSI. Estos identificadores tienen valores predefinidos y se pueden usar directamente con estructuras FORMATETC . Con la excepción de CF_HDROP, los identificadores de formato shell no están predefinidos. Con la excepción de DragWindow, tienen el formato CFSTR_XXX. Para diferenciar estos valores de formatos predefinidos, a menudo se conocen como formatos simple. Sin embargo, a diferencia de los formatos predefinidos, deben estar registrados por el origen y el destino antes de que se puedan usar para transferir datos. Para registrar un formato shell, incluya el archivo de encabezado Shlobj.h y pase el identificador de formato CFSTR_XXX a RegisterClipboardFormat. Esta función devuelve un valor de formato de Portapapeles válido, que luego se puede usar como miembro cfFormat de una estructura FORMATETC .

 

Los formatos del Portapapeles de Shell se organizan aquí en tres grupos, en función de cómo se usan.

Formatos para transferir objetos del sistema de archivos

Estos formatos se usan para transferir uno o varios archivos u otros objetos shell.

CF_HDROP

Este formato del Portapapeles se usa al transferir las ubicaciones de un grupo de archivos existentes. A diferencia de los otros formatos de Shell, está predefinido, por lo que no es necesario llamar a RegisterClipboardFormat. Los datos constan de una estructura STGMEDIUM que contiene un objeto de memoria global. El miembro hGlobal de la estructura apunta a una estructura DROPFILES como su miembro hGlobal .

El miembro pFiles de la estructura DROPFILES contiene un desplazamiento a una matriz de caracteres terminada en null doble que contiene los nombres de archivo. Si va a extraer un formato de CF_HDROP de un objeto de datos, puede usar DragQueryFile para extraer nombres de archivo individuales del objeto de memoria global. Si va a crear un formato de CF_HDROP para colocarlo en un objeto de datos, deberá construir la matriz de nombres de archivo.

La matriz de nombres de archivo consta de una serie de cadenas, cada una de las cuales contiene la ruta de acceso completa de un archivo, incluido el carácter NULL de terminación. Se anexa un carácter null adicional a la cadena final para finalizar la matriz. Por ejemplo, si los archivos c:\temp1.txt y c:\temp2.txt se transfieren, la matriz de caracteres tiene el siguiente aspecto:

c:\temp1.txt'\0'c:\temp2.txt'\0''\0'

Nota

En este ejemplo, se usa '\0' para representar el carácter null , no los caracteres literales que se deben incluir.

Si el objeto se copió en el Portapapeles como parte de una operación de arrastrar y colocar, el miembro pt de la estructura DROPFILES contiene las coordenadas del punto donde se quitó el objeto. Puede usar DragQueryPoint para extraer las coordenadas del cursor.

Si este formato está presente en un objeto de datos, un bucle de arrastre OLE simula WM_DROPFILES funcionalidad con destinos de colocación que no son OLE. Esto es importante si la aplicación es el origen de una operación de arrastrar y colocar en un sistema Windows 3.1.

CFSTR_FILECONTENTS

Este identificador de formato se usa con el formato CFSTR_FILEDESCRIPTOR para transferir datos como si fuera un archivo, independientemente de cómo se almacene realmente. Los datos constan de una estructura STGMEDIUM que representa el contenido de un archivo. Normalmente, el archivo se representa como un objeto de secuencia, lo que evita tener que colocar el contenido del archivo en memoria. En ese caso, el miembro tymed de la estructura STGMEDIUM se establece en TYMED_ISTREAM y el archivo se representa mediante una interfaz IStream . El archivo también puede ser un objeto de almacenamiento o memoria global (TYMED_ISTORAGE o TYMED_HGLOBAL). El formato de CFSTR_FILEDESCRIPTOR asociado contiene una estructura FILEDESCRIPTOR para cada archivo que especifica el nombre y los atributos del archivo.

El destino trata los datos asociados a un formato de CFSTR_FILECONTENTS como si fuera un archivo. Cuando el destino llama a IDataObject::GetData para extraer los datos, especifica un archivo determinado estableciendo el miembro lindex de la estructura FORMATETC en el índice de base cero de la estructura FILEDESCRIPTOR del archivo en el formato de CFSTR_FILEDESCRIPTOR adjunto. A continuación, el destino usa el puntero de interfaz devuelto o el identificador de memoria global para extraer los datos.

CFSTR_FILEDESCRIPTOR

Este identificador de formato se usa con el formato CFSTR_FILECONTENTS para transferir datos como un grupo de archivos. Estos dos formatos son la manera preferida de transferir objetos shell que no se almacenan como archivos del sistema de archivos. Por ejemplo, estos formatos se pueden usar para transferir un grupo de mensajes de correo electrónico como archivos individuales, aunque cada correo electrónico se almacene realmente como un bloque de datos en una base de datos. Los datos constan de una estructura STGMEDIUM que contiene un objeto de memoria global. El miembro hGlobal de la estructura apunta a una estructura FILEGROUPDESCRIPTOR seguida de una matriz que contiene una estructura FILEDESCRIPTOR para cada archivo del grupo. Para cada estructura FILEDESCRIPTOR , hay un formato de CFSTR_FILECONTENTS independiente que contiene el contenido del archivo. Para identificar el formato de CFSTR_FILECONTENTS de un archivo determinado, establezca el valor lIndex de la estructura FORMATETC en el índice de base cero de la estructura FILEDESCRIPTOR del archivo.

El formato CFSTR_FILEDESCRIPTOR se usa normalmente para transferir datos como si fuera un grupo de archivos, independientemente de cómo se almacene realmente. Desde la perspectiva del destino, cada formato de CFSTR_FILECONTENTS representa un único archivo y se trata en consecuencia. Sin embargo, el origen puede almacenar los datos de cualquier manera que elija. Aunque un formato de CSFTR_FILECONTENTS podría corresponder a un único archivo, también podría representar, por ejemplo, los datos extraídos por el origen de una base de datos o un documento de texto.

CFSTR_FILENAME

Este identificador de formato se usa para transferir un único archivo. Los datos constan de una estructura STGMEDIUM que contiene un objeto de memoria global. El miembro hGlobal de la estructura apunta a una sola cadena terminada en null que contiene la ruta de acceso completa del archivo. Este formato se ha reemplazado por CF_HDROP, pero es compatible con versiones anteriores con las aplicaciones de Windows 3.1.

CFSTR_FILENAMEMAP

Este identificador de formato se usa cuando se cambia el nombre de un grupo de archivos en CF_HDROP formato, así como se transfiere. Los datos constan de una estructura STGMEDIUM que contiene un objeto de memoria global. El miembro hGlobal de la estructura apunta a una matriz de caracteres doble terminada en null. Esta matriz contiene un nuevo nombre para cada archivo, en el mismo orden en que los archivos se muestran en el formato CF_HDROP adjunto. El formato de la matriz de caracteres es el mismo que el usado por CF_HDROP para enumerar los archivos transferidos.

CFSTR_MOUNTEDVOLUME

Este identificador de formato se usa para transferir una ruta de acceso en un volumen montado. Es similar a CF_HDROP, pero solo contiene una única ruta de acceso y puede controlar las cadenas de ruta de acceso más largas que podrían ser necesarias para representar una ruta de acceso cuando el volumen está montado en una carpeta. Los datos constan de una estructura STGMEDIUM que contiene un objeto de memoria global. El miembro hGlobal de la estructura apunta a una única cadena terminada en null que contiene la ruta de acceso de archivo completa. La cadena de ruta de acceso debe terminar con un carácter "\", seguido del valor NULL de terminación.

Antes de Windows 2000, los volúmenes solo se podían montar en letras de unidad. Para los sistemas Windows 2000 y versiones posteriores con una unidad con formato NTFS, también puedes montar volúmenes en carpetas vacías. Esta característica permite montar un volumen sin tomar una letra de unidad. El volumen montado puede usar cualquier formato admitido actualmente, incluidos FAT, FAT32, NTFS y CDFS.

Puede agregar páginas a una hoja de propiedades de Propiedades de unidad mediante la implementación de un controlador de hoja de propiedades. Si el volumen se monta en una letra de unidad, shell pasa la información de ruta de acceso al controlador con el formato CF_HDROP . Con los sistemas Windows 2000 y versiones posteriores, el formato CF_HDROP se usa cuando un volumen se monta en una letra de unidad, igual que con los sistemas anteriores. Sin embargo, si se monta un volumen en una carpeta, se usa el identificador de formato CFSTR_MOUNTEDVOLUME en lugar de CF_HDROP.

Si solo se usarán letras de unidad para montar volúmenes, solo se usará CF_HDROP y los controladores de hojas de propiedades existentes funcionarán como lo hicieron con los sistemas anteriores. Sin embargo, si desea que el controlador muestre una página para volúmenes montados en carpetas, así como letras de unidad, el controlador debe ser capaz de comprender los formatos de CSFTR_MOUNTEDVOLUME y CF_HDROP.

CFSTR_SHELLIDLIST

Este identificador de formato se usa al transferir las ubicaciones de uno o varios objetos de espacio de nombres existentes. Se usa de la misma manera que CF_HDROP, pero contiene PIDLs en lugar de rutas de acceso del sistema de archivos. El uso de PIDLs permite que el formato de CFSTR_SHELLIDLIST controle objetos virtuales, así como objetos del sistema de archivos. Los datos son una estructura STGMEDIUM que contiene un objeto de memoria global. El miembro hGlobal de la estructura apunta a una estructura CIDA .

El miembro aoffset de la estructura CIDA es una matriz que contiene desplazamientos al principio de la estructura ITEMIDLIST para cada PIDL que se transfiere. Para extraer un PIDL determinado, determine primero su índice. A continuación, agregue el valor aoffset que corresponde a ese índice a la dirección de la estructura CIDA .

El primer elemento de aoffset contiene un desplazamiento al PIDL completo de una carpeta primaria. Si este PIDL está vacío, la carpeta primaria es el escritorio. Cada uno de los elementos restantes de la matriz contiene un desplazamiento a uno de los PIDL que se van a transferir. Todos estos PIDL son relativos al PIDL de la carpeta primaria.

Las dos macros siguientes se pueden usar para recuperar las PIDL de una estructura CIDA . La primera toma un puntero a la estructura y recupera el PIDL de la carpeta primaria. El segundo toma un puntero a la estructura y recupera uno de los otros PIDL, identificado por su índice de base cero.

#define GetPIDLFolder(pida) (LPCITEMIDLIST)(((LPBYTE)pida)+(pida)->aoffset[0])

#define GetPIDLItem(pida, i) (LPCITEMIDLIST)(((LPBYTE)pida)+(pida)->aoffset[i+1])

Nota

El valor devuelto por estas macros es un puntero a la estructura ITEMIDLIST de PIDL. Dado que estas estructuras varían en longitud, debe determinar el final de la estructura caminando por cada una de las estructuras SHITEMID de la estructura ITEMIDLIST hasta alcanzar el valor NULL de dos bytes que marca el final.

CFSTR_SHELLIDLISTOFFSET

Este identificador de formato se usa con formatos como CF_HDROP, CFSTR_SHELLIDLIST y CFSTR_FILECONTENTS para especificar la posición de un grupo de objetos después de una transferencia. Los datos constan de una estructura STGMEDIUM que contiene un objeto de memoria global. El miembro hGlobal de la estructura apunta a una matriz de estructuras POINT . La primera estructura especifica las coordenadas de pantalla, en píxeles, de la esquina superior izquierda del rectángulo que incluye el grupo. El resto de las estructuras especifican las ubicaciones de los objetos individuales en relación con la posición del grupo. Deben estar en el mismo orden que el usado para enumerar los objetos en el formato asociado.

Formatos para transferir objetos virtuales

El formato CFSTR_SHELLIDLIST se puede usar para transferir objetos virtuales y del sistema de archivos. Sin embargo, también hay varios formatos especializados para transferir tipos concretos de objetos virtuales.

CFSTR_NETRESOURCES

Este identificador de formato se usa al transferir recursos de red, como un dominio o un servidor. Los datos son una estructura STGMEDIUM que contiene un objeto de memoria global. El miembro hGlobal de la estructura apunta a una estructura NRESARRAY . El miembro nr de esa estructura indica una estructura NETRESOURCE cuyo miembro lpRemoteName contiene una cadena terminada en null que identifica el recurso de red. A continuación, el destino de colocación puede usar los datos con cualquiera de las funciones de la API de redes de Windows (WNet), como WNetAddConnection, para realizar operaciones de red en el objeto.

CFSTR_PRINTERGROUP

Este identificador de formato se usa al transferir los nombres descriptivos de las impresoras. Los datos son una estructura STGMEDIUM que contiene un objeto de memoria global. El miembro hGlobal de la estructura apunta a una cadena con el mismo formato que el usado con CF_HDROP. Sin embargo, el miembro pFiles de la estructura DROPFILES contiene uno o varios nombres descriptivos de impresoras en lugar de rutas de acceso de archivo.

CFSTR_INETURL

Este identificador de formato reemplaza CFSTR_SHELLURL (en desuso). Si desea que la aplicación manipule las direcciones URL del Portapapeles, use CFSTR_INETURL en lugar de CFSTR_SHELLURL (en desuso). Este formato proporciona la mejor representación del Portapapeles de una única dirección URL. Si no se define UNICODE, la aplicación recupera la versión CF_TEXT/CFSTR_SHELLURL de la dirección URL. Si se define UNICODE, la aplicación recupera la versión CF_UNICODE de la dirección URL.

CFSTR_SHELLURL (en desuso)

Nota

Este identificador de formato ha quedado en desuso; use CFSTR_INETURL en su lugar.

 

Formatos para la comunicación entre el origen y el destino

Estos identificadores de formato permiten la comunicación entre el origen y el destino. Los formatos acompañan a los datos y proporcionan a las aplicaciones un mayor grado de control sobre las operaciones move-copy-paste o drag-and-drop que implican objetos shell.

CFSTR_INDRAGLOOP

Un objeto de datos usa este identificador de formato para indicar si está en un bucle de arrastrar y colocar. Los datos son una estructura STGMEDIUM que contiene un objeto de memoria global. El miembro hGlobal de la estructura apunta a un valor DWORD . Si el valor DWORD es distinto de cero, el objeto de datos se encuentra dentro de un bucle de arrastrar y colocar. Si el valor se establece en cero, el objeto de datos no está dentro de un bucle de arrastrar y colocar.

Algunos destinos de colocación pueden llamar a IDataObject::GetData e intentar extraer datos mientras el objeto sigue dentro del bucle de arrastrar y colocar. La representación completa del objeto para cada repetición puede hacer que el cursor de arrastre se detenga. Si el objeto de datos admite CFSTR_INDRAGLOOP, el destino puede usar ese formato para comprobar el estado del bucle de arrastrar y colocar y evitar la representación intensiva de memoria del objeto hasta que realmente se quite. Los formatos que consumen mucha memoria para representarse deben incluirse en el enumerador FORMATETC y en las llamadas a IDataObject::QueryGetData. Si el objeto de datos no establece CFSTR_INDRAGLOOP, debe actuar como si el valor se establece en cero.

CFSTR_LOGICALPERFORMEDDROPEFFECT

Versión 5.0. Este identificador de formato permite que un origen de eliminación llame al método IDataObject::GetData del objeto de datos para determinar el resultado de una transferencia de datos de Shell. Los datos son una estructura STGMEDIUM que contiene un objeto de memoria global. El miembro hGlobal de la estructura apunta a un DWORD que contiene un valor DROPEFFECT .

El identificador de formato CFSTR_PERFORMEDDROPEFFECT estaba pensado para permitir que el destino indique al objeto de datos qué operación tuvo lugar realmente. Sin embargo, el Shell usa movimientos optimizados para objetos del sistema de archivos siempre que sea posible. En ese caso, el Shell normalmente establece el valor de CFSTR_PERFORMEDDROPEFFECT en DROPEFFECT_NONE, para indicar al objeto de datos que se han eliminado los datos originales. Por lo tanto, el origen no puede usar el valor de CFSTR_PERFORMEDDROPEFFECT para determinar qué operación ha tenido lugar. Aunque la mayoría de los orígenes no necesitan esta información, hay algunas excepciones. Por ejemplo, aunque los movimientos optimizados eliminan la necesidad de que un origen elimine los datos, es posible que el origen todavía tenga que actualizar una base de datos relacionada para indicar que los archivos se han movido o copiado.

Si un origen necesita saber qué operación tuvo lugar, puede llamar al método IDataObject::GetData del objeto de datos y solicitar el formato CFSTR_LOGICALPERFORMEDDROPEFFECT. Este formato refleja básicamente lo que sucede desde el punto de vista del usuario una vez completada la operación. Si se crea un nuevo archivo y se elimina el archivo original, el usuario ve una operación de movimiento y el valor de datos del formato se establece en DROPEFFECT_MOVE. Si el archivo original todavía está allí, el usuario ve una operación de copia y el valor de datos del formato se establece en DROPEFFECT_COPY. Si se creó un vínculo, el valor de datos del formato se DROPEFFECT_LINK.

CFSTR_PASTESUCCEEDED

El destino usa este identificador de formato para informar al objeto de datos, a través de su método IDataObject::SetData , de que se realizó correctamente una operación de eliminación al pegar. Los datos son una estructura STGMEDIUM que contiene un objeto de memoria global. El miembro hGlobal de la estructura apunta a un DWORD que contiene un valor DROPEFFECT . Este formato se usa para notificar al objeto de datos que debe completar la operación de corte y eliminar los datos originales, si es necesario. Para obtener más información, vea Operaciones de eliminación al pegar.

CFSTR_PERFORMEDDROPEFFECT

El destino usa este identificador de formato para informar al objeto de datos a través de su método IDataObject::SetData del resultado de una transferencia de datos. Los datos son una estructura STGMEDIUM que contiene un objeto de memoria global. El miembro hGlobal de la estructura apunta a un DWORD establecido en el valor DROPEFFECT adecuado, normalmente DROPEFFECT_MOVE o DROPEFFECT_COPY.

Este formato se usa normalmente cuando el resultado de una operación se puede mover o copiar, como en una operación optimizada de movimiento o eliminación al pegar. Proporciona una manera confiable para que el destino indique al objeto de datos lo que realmente ha ocurrido. Se introdujo porque el valor de pdwEffect devuelto por DoDragDrop no indica de forma confiable qué operación tuvo lugar. El formato CFSTR_PERFORMEDDROPEFFECT es la manera confiable de indicar que se ha realizado un movimiento no optimizado.

CFSTR_PREFERREDDROPEFFECT

El origen usa este identificador de formato para especificar si su método preferido de transferencia de datos se mueve o copia. Un destino de eliminación solicita este formato llamando al método IDataObject::GetData del objeto de datos. Los datos son una estructura STGMEDIUM que contiene un objeto de memoria global. El miembro hGlobal de la estructura apunta a un valor DWORD . Este valor se establece en DROPEFFECT_MOVE si se prefiere una operación de traslado o DROPEFFECT_COPY si se prefiere una operación de copia.

Esta característica se usa cuando un origen puede admitir una operación de movimiento o copia. Usa el formato CFSTR_PREFERREDDROPEFFECT para comunicar su preferencia al destino. Dado que el destino no está obligado a respetar la solicitud, el destino debe llamar al método IDataObject::SetData del origen con un formato de CFSTR_PERFORMEDDROPEFFECT para indicar al objeto de datos qué operación se realizó realmente.

Con una operación de eliminación al pegar , el formato CFSTR_PREFERREDDROPFORMAT se usa para indicar al destino si el origen realizó una copia o cortar. Con una operación de arrastrar y colocar, puede usar CFSTR_PREFERREDDROPFORMAT para especificar la acción del shell. Si este formato no está presente, el Shell realiza una acción predeterminada, en función del contexto. Por ejemplo, si un usuario arrastra un archivo de un volumen y lo coloca en otro volumen, la acción predeterminada del Shell es copiar el archivo. Al incluir un formato de CFSTR_PREFERREDDROPFORMAT en el objeto de datos, puede invalidar la acción predeterminada e indicar explícitamente al Shell que copie, mueva o vincule el archivo. Si el usuario decide arrastrar con el botón derecho, CFSTR_PREFERREDDROPFORMAT especifica el comando predeterminado en el menú contextual de arrastrar y colocar . El usuario todavía puede elegir otros comandos en el menú.

Antes de Microsoft Internet Explorer 4.0, una aplicación indicó que transfiere tipos de archivo de acceso directo estableciendo FD_LINKUI en el miembro dwFlags de la estructura FILEDESCRIPTOR . A continuación, los destinos tenían que usar una llamada potencialmente lenta a IDataObject::GetData para averiguar si se estableció la marca de FD_LINKUI. Ahora, la manera preferida de indicar que los accesos directos se transfieren es usar el formato CFSTR_PREFERREDDROPEFFECT establecido en DROPEFFECT_LINK. Sin embargo, para la compatibilidad con versiones anteriores con sistemas anteriores, los orígenes deben seguir configurando la marca FD_LINKUI.

CFSTR_TARGETCLSID

Un destino usa este identificador de formato para proporcionar su CLSID al origen. Los datos son una estructura STGMEDIUM que contiene un objeto de memoria global. El miembro hGlobal de la estructura apunta al GUID clSID del destino de colocación.

Este formato se usa principalmente para permitir que los objetos se eliminen arrastrándolos a la Papelera de reciclaje. Cuando se quita un objeto en la Papelera de reciclaje, se llama al método IDataObject::SetData del origen con un formato CFSTR_TARGETCLSID establecido en clSID de la Papelera de reciclaje (CLSID_RecycleBin). A continuación, el origen puede eliminar el objeto original.

CFSTR_UNTRUSTEDDRAGDROP

Windows Internet Explorer usa este identificador de formato y el Shell de Windows para proporcionar un mecanismo a través del cual bloquear o solicitar operaciones de arrastrar y colocar originadas en Internet Explorer junto con la marca URLACTION_SHELL_ENHANCED_DRAGDROP_SECURITY .

CFSTR_UNTRUSTEDDRAGDROP se agrega mediante el origen de una operación de arrastrar y colocar para especificar que el objeto de datos puede contener datos no confiables. Los datos se representan mediante una estructura STGMEDIUM que contiene un objeto de memoria global. El miembro hGlobal de la estructura apunta a un DWORD establecido en una marca de acción de dirección URL adecuada para provocar una comprobación de directiva a través del método IInternetSecurityManager::P rocessUrlAction , con la marca PUAF_ENFORCERESTRICTED .

DragWindow

Este formato se usa en una operación de arrastrar y colocar para identificar la imagen de arrastre (ventana) de un objeto para que su información visual se pueda actualizar dinámicamente. Cuando un objeto se arrastra sobre un destino de colocación, una aplicación actualiza su estructura DROPDESCRIPTION en respuesta al método IDropTarget::D ragOver o IDropSource::GiveFeedback . DROPDESCRIPTION se actualiza con un nuevo valor DROPIMAGETYPE que indica la decoración que se va a aplicar al objeto visual de la ventana de arrastre; por ejemplo, una indicación de que el archivo se está copiando en lugar de moverse o que el objeto no se puede quitar en esa ubicación. Sin embargo, hasta que el objeto recibe un mensaje de DDWM_UPDATEWINDOW , los objetos visuales no se actualizan. Este formato proporciona el HWND de la ventana de arrastre del destinatario al remitente del mensaje DDWM_UPDATEWINDOW .

Los datos del Portapapeles son de tipo TYMED_HGLOBAL. Es una representación DWORD de un HWND. Los datos se pueden pasar a la función ULongToHandle , definida en Basetsd.h, para proporcionar un HWND de 64 bits para su uso en Windows de 64 bits.

Este formato no requiere la inclusión de Shlobj.h.