Форматы буфера обмена оболочки

Форматы буфера обмена оболочки используются для определения типа передаваемых данных оболочки через буфер обмена. Большинство форматов буфера обмена оболочки определяют тип данных, например список имен файлов или указателей на списки идентификаторов элементов (PID). Однако некоторые форматы используются для обмена данными между источником и целевым объектом. Они могут ускорить процесс передачи данных, поддерживая такие операции оболочки, как оптимизированное перемещение и delete_on_paste. Данные оболочки всегда содержатся в объекте данных , использующего структуру FORMATETC в качестве более общего способа описания данных. Элемент cfFormat структуры имеет формат буфера обмена для определенного элемента данных. Другие члены предоставляют дополнительные сведения, такие как механизм передачи данных. Данные содержатся в сопровождающей структуре STGMEDIUM .

Замечание

Стандартные идентификаторы формата буфера обмена имеют форму CF_XXXX. Типичным примером является CF_TEXT, который используется для передачи текстовых данных ANSI. Эти идентификаторы имеют предопределенные значения и могут использоваться непосредственно со структурами FORMATETC . За исключением CF_HDROP идентификаторы формата оболочки не определены. За исключением DragWindow, они имеют форму CFSTR_XXXX. Чтобы отличить эти значения от предопределенных форматов, они часто называются простыми форматами. Однако, в отличие от стандартных форматов, они должны быть зарегистрированы как источником, так и целевым объектом, прежде чем их можно будет использовать для передачи данных. Чтобы зарегистрировать формат оболочки, включите файл заголовка Shlobj.h и передайте идентификатор формата CFSTR_XXX вRegisterClipboardFormat. Эта функция возвращает допустимое значение формата буфера обмена, которое затем можно использовать в качестве члена cfFormat структуры FORMATETC .

 

Форматы буфера обмена оболочки организованы здесь в три группы на основе того, как они используются.

Форматы передачи объектов файловой системы

Эти форматы используются для передачи одного или нескольких файлов или других объектов Оболочки.

CF_HDROP

Этот формат буфера обмена используется при передаче расположений группы существующих файлов. В отличие от других форматов оболочки, он предопределен, поэтому не требуется вызывать RegisterClipboardFormat. Данные состоят из структуры STGMEDIUM , содержащей глобальный объект памяти. Элемент hGlobal структуры указывает на структуру DROPFILES в качестве его элемента hGlobal .

Элемент pFiles структуры DROPFILES содержит смещение к двойному массиву символов, завершаемого значением NULL, который содержит имена файлов. При извлечении формата CF_HDROP из объекта данных можно использовать DragQueryFile для извлечения отдельных имен файлов из глобального объекта памяти. Если вы создаете формат CF_HDROP для размещения в объекте данных, необходимо создать массив имен файла.

Массив имен файла состоит из ряда строк, каждый из которых содержит полный путь к одному файлу, включая завершающий символ NULL . Дополнительный пустой символ добавляется к последней строке, чтобы завершить массив. Например, если передаются файлы c:\temp1.txt и c:\temp2.txt, массив символов выглядит следующим образом:

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

Замечание

В этом примере "\0" используется для представления null-символов, а не литеральных символов, которые должны быть включены.

Если объект был скопирован в буфер обмена в рамках операции перетаскивания, элемент pt структуры DROPFILES содержит координаты точки, в которой был удален объект. Для извлечения координат курсора можно использовать DragQueryPoint .

Если этот формат присутствует в объекте данных, цикл перетаскивания OLE имитирует функции WM_DROPFILES с целевыми объектами удаления без OLE. Это важно, если приложение является источником операции перетаскивания в системе Windows 3.1.

CFSTR_FILECONTENTS

Этот идентификатор формата используется с форматом CFSTR_FILEDESCRIPTOR для передачи данных, как если бы он был файлом независимо от того, как он фактически хранится. Данные состоят из структуры STGMEDIUM , представляющей содержимое одного файла. Файл обычно представляется как объект потока, что позволяет избежать необходимости размещать содержимое файла в памяти. В этом случае для элемента структуры STGMEDIUM задано значение TYMED_ISTREAM, а файл представлен интерфейсом IStream. Файл также может быть хранилищем или глобальным объектом памяти (TYMED_ISTORAGE или TYMED_HGLOBAL). Связанный формат CFSTR_FILEDESCRIPTOR содержит структуру FILEDESCRIPTOR для каждого файла, указывающего имя и атрибуты файла.

Целевой объект обрабатывает данные, связанные с форматом CFSTR_FILECONTENTS, как если бы он был файлом. Когда целевой объект вызывает IDataObject::GetData для извлечения данных, он указывает конкретный файл, задав элемент lindex структуры FORMATETC в отсчитываемый от нуля индекс структуры FILEDESCRIPTOR файла в сопровождающем CFSTR_FILEDESCRIPTOR формате. Затем целевой объект использует возвращаемый указатель интерфейса или глобальный дескриптор памяти для извлечения данных.

CFSTR_FILEDESCRIPTOR

Этот идентификатор формата используется с форматом CFSTR_FILECONTENTS для передачи данных в виде группы файлов. Эти два формата являются предпочтительным способом передачи объектов Оболочки, которые не хранятся в виде файлов файловой системы. Например, эти форматы можно использовать для передачи группы сообщений электронной почты в виде отдельных файлов, даже если каждая электронная почта фактически хранится в виде блока данных в базе данных. Данные состоят из структуры STGMEDIUM , содержащей глобальный объект памяти. Элемент hGlobal структуры указывает на структуру FILEGROUPDESCRIPTOR , за которой следует массив, содержащий одну структуру FILEDESCRIPTOR для каждого файла в группе. Для каждой структуры FILEDESCRIPTOR существует отдельный формат CFSTR_FILECONTENTS, содержащий содержимое файла. Чтобы определить формат CFSTR_FILECONTENTS определенного файла, задайте значение lIndex структуры FORMATETC на основе отсчитываемого от нуля индекса структуры FILEDESCRIPTOR файла.

Формат CFSTR_FILEDESCRIPTOR обычно используется для передачи данных, как если бы он был группой файлов, независимо от того, как он фактически хранится. С точки зрения целевого объекта каждый формат CFSTR_FILECONTENTS представляет один файл и обрабатывается соответствующим образом. Однако источник может хранить данные любым способом. Хотя формат CSFTR_FILECONTENTS может соответствовать одному файлу, он также может представлять данные, извлеченные источником из базы данных или текстового документа.

CFSTR_FILENAME

Этот идентификатор формата используется для передачи одного файла. Данные состоят из структуры STGMEDIUM , содержащей глобальный объект памяти. Элемент hGlobal структуры указывает на одну строку, завершающую значение NULL, содержащую полный путь к файлу. Этот формат заменен CF_HDROP, но поддерживается для обратной совместимости с приложениями Windows 3.1.

CFSTR_FILENAMEMAP

Этот идентификатор формата используется при переименовании группы файлов в CF_HDROP формате, а также передачи. Данные состоят из структуры STGMEDIUM , содержащей глобальный объект памяти. Элемент hGlobal структуры указывает на двойной массив символов, завершаемый значением NULL. Этот массив содержит новое имя для каждого файла в том же порядке, что и файлы в соответствующем формате CF_HDROP. Формат массива символов совпадает с форматом, используемым CF_HDROP для перечисления передаваемых файлов.

CFSTR_MOUNTEDVOLUME

Этот идентификатор формата используется для передачи пути к подключенному тому. Он похож на CF_HDROP, но содержит только один путь и может обрабатывать более длинные строки пути, которые могут потребоваться для представления пути при подключении тома к папке. Данные состоят из структуры STGMEDIUM , содержащей глобальный объект памяти. Элемент hGlobal структуры указывает на одну строку, завершающую значение NULL, содержащую полный путь к файлу. Строка пути должна заканчиваться символом \, а затем завершающим значением NULL.

До Windows 2000 тома можно подключить только на буквах диска. Для Windows 2000 и более поздних систем с отформатированным диском NTFS можно также подключить тома в пустых папках. Эта функция позволяет подключить том, не принимая букву диска. Подключенный том может использовать любой поддерживаемый формат, включая FAT, FAT32, NTFS и CDFS.

Страницы можно добавить на лист свойств диска, реализуя обработчик листа свойств свойств. Если том подключен к букве диска, оболочка передает сведения о пути обработчику с помощью формата CF_HDROP . При использовании Windows 2000 и более поздних систем формат CF_HDROP используется при подключении тома на букве диска, как и в предыдущих системах. Однако если том подключен к папке, вместо CF_HDROP используется идентификатор формата CFSTR_MOUNTEDVOLUME .

Если для подключения томов будут использоваться только буквы дисков, будут использоваться только CF_HDROP , а существующие обработчики листов свойств будут работать, как и в предыдущих системах. Однако если обработчик должен отобразить страницу томов, подключенных к папкам, а также буквам диска, обработчик должен иметь возможность понять как форматы CSFTR_MOUNTEDVOLUME, так и CF_HDROP.

CFSTR_SHELLIDLIST

Этот идентификатор формата используется при передаче расположений одного или нескольких существующих объектов пространства имен. Он используется так же, как и CF_HDROP, но содержит PID-адреса вместо путей файловой системы. Использование ПИН-адресов позволяет формату CFSTR_SHELLIDLIST обрабатывать виртуальные объекты, а также объекты файловой системы. Данные — это структура STGMEDIUM , содержащая глобальный объект памяти. Элемент hGlobal структуры указывает на структуру CIDA .

Элемент aoffset структуры CIDA — это массив, содержащий смещения к началу структуры ITEMIDLIST для каждого передаваемого PIDL. Чтобы извлечь определенный PIDL, сначала определите его индекс. Затем добавьте значение aoffset , соответствующее этому индексу, в адрес структуры CIDA .

Первый элемент aoffset содержит смещение к полному идентификатору PIDL родительской папки. Если этот PIDL пуст, родительская папка — это рабочий стол. Каждый из оставшихся элементов массива содержит смещение к одному из передаваемых ПИН-адресов. Все эти ИДЕНТИФИКАТОРЫ относятся к PIDL родительской папки.

Следующие два макроса можно использовать для получения ПИН-адресов из структуры CIDA . Первый принимает указатель на структуру и извлекает PIDL родительской папки. Второй принимает указатель на структуру и извлекает один из других ПИН-адресов, определяемых его отсчитываемым от нуля индексом.

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

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

Замечание

Значение, возвращаемое этими макросами, является указателем на структуру ITEMIDLIST PIDL. Так как эти структуры зависят от длины, необходимо определить конец структуры, перейдя по каждой из структур SHITEMIDLIST структуры ITEMIDID, пока не достигнет двухбайтового NULL, который помечает конец.

CFSTR_SHELLIDLISTOFFSET

Этот идентификатор формата используется с такими форматами, как CF_HDROP, CFSTR_SHELLIDLIST и CFSTR_FILECONTENTS , чтобы указать положение группы объектов после передачи. Данные состоят из структуры STGMEDIUM , содержащей глобальный объект памяти. Элемент hGlobal структуры указывает на массив структур POINT . Первая структура задает координаты экрана (в пикселях) левого верхнего угла прямоугольника, включающего группу. Оставшаяся часть структур указывает расположения отдельных объектов относительно положения группы. Они должны находиться в том же порядке, что и для перечисления объектов в связанном формате.

Форматы для передачи виртуальных объектов

Формат CFSTR_SHELLIDLIST можно использовать для передачи файловой системы и виртуальных объектов. Однако существует несколько специализированных форматов для передачи определенных типов виртуальных объектов.

CFSTR_NETRESOURCES

Этот идентификатор формата используется при передаче сетевых ресурсов, таких как домен или сервер. Данные — это структура STGMEDIUM , содержащая глобальный объект памяти. Элемент hGlobal структуры указывает на структуру NRESARRAY . Элемент nr этой структуры указывает структуру NETRESOURCE, элемент lpRemoteName которого содержит строку, завершающую значение NULL, идентифицируя сетевой ресурс. Затем целевой объект удаления может использовать данные с любым из функций API Windows Сети (WNet) API, например WNetAddConnection для выполнения сетевых операций с объектом.

CFSTR_PRINTERGROUP

Этот идентификатор формата используется при передаче понятных имен принтеров. Данные — это структура STGMEDIUM , содержащая глобальный объект памяти. Элемент hGlobal структуры указывает на строку в том же формате, что и в CF_HDROP. Однако элемент pFiles структуры DROPFILES содержит одно или несколько понятных имен принтеров вместо путей к файлам.

CFSTR_INETURL

Этот идентификатор формата заменяет CFSTR_SHELLURL (не рекомендуется). Если вы хотите, чтобы приложение использовало URL-адреса буфера обмена, используйте CFSTR_INETURL вместо CFSTR_SHELLURL (не рекомендуется). Этот формат обеспечивает лучшее представление буфера обмена для одного URL-адреса. Если ЮНИКОД не определен, приложение получает версию URL-адреса CF_TEXT/CFSTR_SHELLURL. Если определен ЮНИКОД, приложение извлекает CF_UNICODE версию URL-адреса.

CFSTR_SHELLURL (не рекомендуется)

Замечание

Этот идентификатор формата устарел; вместо этого используйте CFSTR_INETURL.

 

Форматы обмена данными между источником и целевым объектом

Эти идентификаторы формата позволяют осуществлять обмен данными между источником и целевым объектом. Форматы сопровождают данные и предоставляют приложениям большую степень контроля над операциями перемещения и вставки или перетаскивания с объектами Оболочки.

CFSTR_INDRAGLOOP

Этот идентификатор формата используется объектом данных, чтобы указать, находится ли он в цикле перетаскивания. Данные — это структура STGMEDIUM , содержащая глобальный объект памяти. Элемент hGlobal структуры указывает на значение DWORD . Если значение DWORD ненулевое, объект данных находится в цикле перетаскивания. Если значение равно нулю, объект данных не находится в цикле перетаскивания.

Некоторые целевые объекты удаления могут вызывать IDataObject::GetData и пытаться извлечь данные, пока объект находится в цикле перетаскивания. Полная отрисовка объекта для каждого такого вхождения может привести к остановке курсора перетаскивания. Если объект данных поддерживает CFSTR_INDRAGLOOP, целевой объект может использовать этот формат, чтобы проверить состояние цикла перетаскивания и избежать интенсивной отрисовки объекта, пока он не будет удален. Форматы, которые являются интенсивными для отрисовки памяти, по-прежнему должны быть включены в перечислитель FORMATETC и в вызовы IDataObject::QueryGetData. Если объект данных не задает CFSTR_INDRAGLOOP, он должен действовать так, как если значение равно нулю.

CFSTR_LOGICALPERFORMEDDROPEFFECT

Версия 5.0.Этот идентификатор формата позволяет источнику перетаскивания вызывать метод IDataObject объекта данных::GetData , чтобы определить результат передачи данных Оболочки. Данные — это структура STGMEDIUM , содержащая глобальный объект памяти. Элемент hGlobal структуры указывает на DWORD, содержащий значение DROPEFFECT .

Идентификатор формата CFSTR_PERFORMEDDROPEFFECT предназначен для указания целевому объекту данных, что на самом деле произошло. Однако оболочка использует оптимизированные перемещения для объектов файловой системы всякий раз, когда это возможно. В этом случае оболочка обычно задает значение CFSTR_PERFORMEDDROPEFFECT DROPEFFECT_NONE, чтобы указать объекту данных, который был удален исходными данными. Таким образом, источник не может использовать значение CFSTR_PERFORMEDDROPEFFECT, чтобы определить, какая операция произошла. Хотя большинство источников не нуждаются в этой информации, существуют некоторые исключения. Например, несмотря на то, что оптимизированные перемещения устраняют необходимость удаления любых данных источника, источник может по-прежнему обновить связанную базу данных, чтобы указать, что файлы были перемещены или скопированы.

Если источнику нужно знать, какая операция произошла, он может вызвать метод IDataObject объекта данных::GetData и запросить формат CFSTR_LOGICALPERFORMEDDROPEFFECT. Этот формат по сути отражает то, что происходит с точки зрения пользователя после завершения операции. Если создается новый файл и исходный файл удаляется, пользователь видит операцию перемещения, а для значения данных формата задано значение DROPEFFECT_MOVE. Если исходный файл по-прежнему существует, пользователь видит операцию копирования, а для значения данных формата задано значение DROPEFFECT_COPY. Если была создана ссылка, значение данных формата будет DROPEFFECT_LINK.

CFSTR_PASTESUCCEEDED

Этот идентификатор формата используется целевым объектом для информирования объекта данных с помощью метода IDataObject::SetData , что операция удаления вставить выполнена успешно. Данные — это структура STGMEDIUM , содержащая глобальный объект памяти. Элемент hGlobal структуры указывает на DWORD , содержащий значение DROPEFFECT . Этот формат используется для уведомления объекта данных о том, что он должен завершить операцию выреза и удалить исходные данные при необходимости. Дополнительные сведения см. в разделе "Операции удаления по вставки".

CFSTR_PERFORMEDDROPEFFECT

Этот идентификатор формата используется целевым объектом для информирования объекта данных с помощью метода IDataObject::SetData результата передачи данных. Данные — это структура STGMEDIUM , содержащая глобальный объект памяти. Элемент hGlobal структуры указывает на DWORD , заданное соответствующим значением DROPEFFECT , обычно DROPEFFECT_MOVE или DROPEFFECT_COPY.

Обычно этот формат используется, когда результат операции может быть перемещением или копированием, например в оптимизированной операции перемещения или удаления при вставке. Он предоставляет надежный способ для целевого объекта данных, чтобы сообщить объекту данных о том, что на самом деле произошло. Оно было введено, так как значение pdwEffect , возвращаемое DoDragDrop , не надежно указывает, какая операция произошла. Формат CFSTR_PERFORMEDDROPEFFECT — это надежный способ указать, что произошел неоптимизированный шаг.

CFSTR_PREFERREDDROPEFFECT

Этот идентификатор формата используется источником, чтобы указать, является ли его предпочтительный метод передачи данных перемещением, копированием или ссылкой. Целевой объект удаления запрашивает этот формат путем вызова метода IDataObject объекта данных::GetData . Данные — это структура STGMEDIUM , содержащая глобальный объект памяти. Элемент hGlobal структуры указывает на значение DWORD . Это значение имеет значение DROPEFFECT_MOVE если операция перемещения предпочтительна, DROPEFFECT_COPY, если операция копирования предпочтительна или DROPEFFECT_LINK, если операция ссылки предпочтительна.

Эта функция используется, когда источник может поддерживать операцию перемещения или копирования. Он использует формат CFSTR_PREFERREDDROPEFFECT для передачи своих предпочтений целевому объекту. Так как целевой объект не обязан соблюдать запрос, целевой объект должен вызвать метод IDataObject источника::SetData с форматом CFSTR_PERFORMEDDROPEFFECT , чтобы сообщить объекту данных, какой операции был выполнен.

При использовании операции удаления при вставеформат CFSTR_PREFERREDDROPEFFECT используется для определения целевого объекта, сделал ли источник вырезать или скопировать. С помощью операции перетаскивания можно использовать формат CFSTR_PREFERREDDROPEFFECT для указания действия оболочки. Если этот формат отсутствует, оболочка выполняет действие по умолчанию на основе контекста. Например, если пользователь перетаскивает файл из одного тома и удаляет его на другой том, действие оболочки по умолчанию заключается в копировании файла. Включив в объект данных CFSTR_PREFERREDDROPEFFECT формат, можно переопределить действие по умолчанию и явно сообщить оболочке копировать, перемещать или связывать файл. Если пользователь выбирает перетаскивание с правой кнопкой, CFSTR_PREFERREDDROPEFFECT формат указывает команду по умолчанию в контекстном меню перетаскивания . Пользователь по-прежнему может выбрать другие команды в меню.

До Microsoft Internet Explorer 4.0 приложение указало, что оно передает типы ярлыков, задав FD_LINKUI в dwFlags член структуры FILEDESCRIPTOR. Затем целевые объекты должны были использовать потенциально длительный вызов IDataObject::GetData , чтобы узнать, был ли установлен флаг FD_LINKUI. Теперь предпочтительный способ указать, что передаются ярлыки, — использовать CFSTR_PREFERREDDROPEFFECT формат, заданный для DROPEFFECT_LINK . Однако для обратной совместимости с старыми системами источники по-прежнему должны задать флаг FD_LINKUI.

CFSTR_TARGETCLSID

Этот идентификатор формата используется целевым объектом для предоставления clSID источнику. Данные — это структура STGMEDIUM , содержащая глобальный объект памяти. Элемент hGlobal структуры указывает на GUID CLSID целевого объекта удаления.

Этот формат используется в основном для разрешения удаления объектов путем перетаскивания их в корзину. При удалении объекта в корзине метод IDataObject::SetData вызывается с CFSTR_TARGETCLSID форматом clSID корзины (CLSID_RecycleBin). Затем источник может удалить исходный объект.

CFSTR_UNTRUSTEDDRAGDROP

Этот идентификатор формата используется Windows Internet Explorer и оболочкой Windows для предоставления механизма блокировки или запроса операций перетаскивания из Internet Explorer в сочетании с флагом URLACTION_SHELL_ENHANCED_DRAGDROP_SECURITY.

CFSTR_UNTRUSTEDDRAGDROP добавляется источником операции перетаскивания, чтобы указать, что объект данных может содержать ненадежные данные. Данные представлены структурой STGMEDIUM , содержащей глобальный объект памяти. Элемент hGlobal структуры указывает на DWORD , заданный для соответствующего флага действия URL-адреса , чтобы вызвать проверку политики с помощью метода IInternetSecurityManager::P rocessUrlAction с помощью флага PUAF_ENFORCERESTRICTED .

Перетаскивание

Этот формат используется в операции перетаскивания для идентификации изображения перетаскивания объекта ( окна), чтобы ее визуальные сведения могли быть динамически обновлены. Если объект перетаскивается по целевому объекту, приложение обновляет структуру DROPDESCRIPTION в ответ на метод IDropTarget::D ragOver или IDropSource::GiveFeedback . DropDESCRIPTION обновляется с новым значением DROPIMAGETYPE, которое указывает, что украшение, которое будет применено к визуальному элементу окна перетаскивания; например, указывает на то, что файл копируется, а не перемещается или объект не может быть удален в это расположение. Однако до тех пор, пока объект не получит сообщение DDWM_UPDATEWINDOW , визуальные элементы не обновляются. Этот формат предоставляет HWND окна перетаскивания получателя отправителю сообщения DDWM_UPDATEWINDOW .

Данные буфера обмена являются типом TYMED_HGLOBAL. Это представление DWORD для HWND. Данные можно передать в функцию ULongToHandle, определенную в Basetsd.h, для предоставления 64-разрядной HWND для использования на 64-разрядной Windows.

Для этого формата не требуется включение Shlobj.h.

 

 

  • Last updated on