Функция SHAddToRecentDocs (shlobj_core.h)

  • Статья

Уведомляет систему о доступе к элементу в целях отслеживания последних и наиболее часто используемых элементов. Эту функцию также можно использовать для очистки всех данных об использовании.

Синтаксис

void SHAddToRecentDocs(
                 UINT    uFlags,
  [in, optional] LPCVOID pv
);

Параметры

uFlags

Тип: UINT

Значение из перечисления SHARD , указывающее форму сведений, на которые указывает параметр pv .

[in, optional] pv

Тип: LPCVOID

Указатель на данные, идентифицирующий элемент, к которому был предоставлен доступ. Элемент можно указать в этом параметре в одной из следующих форм:

Присвойте этому параметру значение NULL , чтобы очистить все данные об использовании всех элементов.

Возвращаемое значение

None

Remarks

Статистика использования, собранная с помощью вызовов этого метода, используется для определения списков элементов, к которым обращаются последние и наиболее часто. Эти списки отображаются в меню Пуск , а в Windows 7 и более поздних версиях — в списке переходов приложения.

Вызов этого метода влияет на следующие области:

  • Обновления списки Последние и Частые для списка переходов связанного приложения.
  • Добавляет ярлык в папку Последние пользователя (FOLDERID_Recent, CSIDL_RECENT). Это отражено в меню Мои последние документы (Windows XP) и Последние элементы (Windows Vista и более поздних версий) в меню Пуск .
  • Добавляет ярлык во вложенное меню "Документы" классического меню "Пуск". (Обратите внимание, что параметр классического меню "Пуск " недоступен в Windows 7 и более поздних версиях.)
Элементы, представленные IShellLink , не добавляются в папку Recent , хотя они отражаются в списке переходов приложения.

В некоторых случаях, когда пользователь открывает элемент через Windows Обозреватель или использует диалоговое окно общего файла для открытия, сохранения или создания файла, оболочка вызывает SHAddToRecentDocs от имени приложения. Приложение, которое имеет пользовательский интерфейс для выбора элементов, должно явно вызывать SHAddToRecentDocs , чтобы обеспечить точную статистику. Повторяющиеся вызовы учитываются системой, поэтому при этом нет риска перекоса данных.

Исполняемые файлы (.exe) фильтруются из списка недавно использовавшихся документов в Windows XP и более поздних версиях. Хотя SHAddToRecentDocs принимает путь к исполняемому файлу, этот файл не будет отображаться в списке Последние элементы .

Папки также принимаются SHAddToRecentDocs, но отображаются только в списке переходов для кнопки Windows Обозреватель панели задач. Папки не отображаются в списке переходов другого приложения.

В некоторых случаях SHAddToRecentDocs пытается зарегистрировать приложение для обработки не зарегистрированного типа файла. Это происходит при следующих обстоятельствах:

  • Приложение явно вызывает SHAddToRecentDocs с типом файла, для обработки который не зарегистрирован. Это также относится к вызовам SHAddToRecentDocs диалоговым окном общего файла от имени приложения, но только в том случае, если диалог используется для открытия файла, а не при его сохранении.
  • Пользователь удаляет файл типа, который приложение не зарегистрировано для обработки на кнопке панели задач приложения.
Эта регистрация выполняется для каждого пользователя.

Для успешного выполнения регистрации необходимо выполнить ряд требований.

  • Приложение должно быть зарегистрировано в HKEY_CLASSES_ROOT\Applications.
  • Эта регистрация не может включать значение NoOpenWith. Дополнительные сведения о NoOpenWith см. в разделе Типы файлов .
  • Эта регистрация не может предоставлять данные в подразделе SupportedTypes . Дополнительные сведения о подразделе SupportedTypes см. в разделе Типы файлов.
  • Исполняемый файл приложения не может быть указан в значении KillList, найденном здесь:
    HKEY_LOCAL_MACHINE
   Software
      Microsoft
         Windows
            CurrentVersion
               Explorer
                  FileAssociation
                     KillList
    Примечание Сторонние приложения не должны изменять значение KillList. Он должен рассматриваться как доступный только для чтения.
     
  • Регистрация приложения HKEY_CLASSES_ROOT\Applications должна иметь набор глаголов по умолчанию, определенных в HKEY_CLASSES_ROOT\Applications\ExampleApp.exe\shell subkey.

    Если SHAddToRecentDocs пытается выполнить регистрацию в результате перетаскивания на кнопку панели задач, подраздел оболочки создается, если он еще не существует, если существующая регистрация приложения не содержит значение NoOpenWith и исполняемый файл приложения не указан в значении KillList.

Подавление вызовов SHAddToRecentDocs

В версиях Windows до Windows 7 тип файла может задать флаг FTA_NoRecentDocs , чтобы предотвратить добавление этого типа файла в папку Последние . Этот механизм также поддерживается в Windows 7 и более поздних версиях. Дополнительные сведения см. в разделе Типы файлов .

SHAddToRecentDocs отслеживает статистику использования документа с помощью глаголов, вызываемых для доступа к этим документам. Команды, предоставленные зарегистрированными обработчиками IContextMenu , отслеживаются. Эти элементы отображаются в меню Мои последние документы (Windows XP) и Последние элементы (Windows Vista). В Windows 7 родительские папки документов отображаются в списке переходов для кнопки Windows Обозреватель панели задач. Однако документы, доступные с помощью этих команд IContextMenu, не отображаются в приложении Jump Списки. Чтобы эти элементы отображались в списке переходов приложения, приложение должно вызывать SHAddToRecentDocs явным образом.

До Windows 7 только open глагол приводил к вызову SHAddToRecentDocs. В Windows 7 и более поздних версиях другие команды также могут создавать статистику использования. Эти сведения используются, чтобы сделать назначения списка переходов более полными и точными.

Однако некоторые классы регистрации сопоставлений типов файлов или отдельные реализации IContextMenu не подходят для такого типа отслеживания. Целью отслеживания использования является создание списка элементов, к которым пользователь, скорее всего, захочет снова получить доступ. Если определенная глаголаdelete, например, изначально вызывается для элемента, к которому пользователь больше не сможет получить доступ, или является дополнительным действием, таким как проверка на наличие вирусов в файле, эта команда не подходит для отслеживания. Классы типов файлов должны удаляться из этого отслеживания с помощью записи реестра NoRecentDocs. NoRecentDocs имеет тип REG_SZ и не имеет связанных данных. Его наличие — это все, что необходимо для предотвращения вызова SHAddToRecentDocs.

Например, расширения контекстного меню и статические команды, зарегистрированные в HKEY_CLASSES_ROOT в таких классах, как "*", "AllFileSystemObjects" или "Folder", не должны отслеживаться. В таких случаях запись NoRecentDocs добавляется в корень ключа класса, как показано ниже, для подавления отслеживания документов, запущенных с помощью любой команды или расширения, зарегистрированных в этом классе:

HKEY_CLASSES_ROOT
   AllFileSystemObjects
      NoRecentDocs

Запись NoRecentDocs по умолчанию назначается подразделам *классов , AllFileSystemObjects, Folder, Directory и DesktopBackground .

Отдельные реализации IContextMenu могут отказаться от отслеживания, добавив подраздел NoRecentDocs в регистрацию объекта COM в подразделе shellex , как показано ниже:

HKEY_CLASSES_ROOT
   CLSID
      {093C7AAB-5E72-454f-A91D-CA1BC991FCEC}
         shellex
            NoRecentDocs

Этот подраздел отсутствует по умолчанию в реализации IContextMenu .

Требования

Требование Значение
Минимальная версия клиента Windows XP [только классические приложения]
Минимальная версия сервера Windows 2000 Server [только классические приложения]
Целевая платформа Windows
Header shlobj_core.h (включая Shlobj.h)
Библиотека Shell32.lib
DLL Shell32.dll (версия 4.0 или более поздняя)
Набор API ext-ms-win-shell-shell32-l1-2-2 (представлено в Windows 10 версии 10.0.14393)

См. также раздел

SHGetFolderLocation

SHGetFolderPath