Função SHAddToRecentDocs (shlobj_core.h)
Notifica o sistema de que um item foi acessado, para fins de acompanhamento desses itens usados mais recentemente e com mais frequência. Essa função também pode ser usada para limpar todos os dados de uso.
Sintaxe
void SHAddToRecentDocs(
UINT uFlags,
[in, optional] LPCVOID pv
);
Parâmetros
uFlags
Tipo: UINT
Um valor da enumeração SHARD que indica a forma das informações apontadas pelo parâmetro pv .
[in, optional] pv
Tipo: LPCVOID
Um ponteiro para os dados que identificam o item que foi acessado. O item pode ser especificado nesse parâmetro em uma das seguintes formas:
- Uma cadeia de caracteres terminada em nulo que contém o caminho e o nome do arquivo do item.
- Um PIDL que identifica o objeto de arquivo do item.
- Somente Windows 7 e posterior. Uma estrutura SHARDAPPIDINFO, SHARDAPPIDINFOIDLIST ou SHARDAPPIDINFOLINK que identifica o item por meio de um AppUserModelID. Consulte IDs de modelo de usuário do aplicativo (AppUserModelIDs) para obter mais informações.
- Somente Windows 7 e posterior. Um objeto IShellLink que identifica o item por meio de um atalho.
Defina esse parâmetro como NULL para limpar todos os dados de uso em todos os itens.
Retornar valor
Nenhum
Comentários
As estatísticas de uso coletadas por meio de chamadas para esse método são usadas para determinar listas de itens acessados mais recentemente e com mais frequência. Essas listas são vistas no menu Iniciar e, no Windows 7 e posterior, na Lista de Atalhos de um aplicativo.
Quando esse método é chamado, ele afeta as seguintes áreas:
- Atualizações as listas Recentes e Frequentes da Lista de Atalhos do aplicativo associado.
- Adiciona um atalho à pasta Recente do usuário (FOLDERID_Recent, CSIDL_RECENT). Isso é refletido no menu Meus Documentos Recentes (Windows XP) e Itens Recentes (Windows Vista e posterior) no menu Iniciar .
- Adiciona um atalho ao submenu Documentos do menu Iniciar Clássico. (Observe que a opção de menu Iniciar Clássico não está disponível no Windows 7 e posterior.)
Em alguns casos, notadamente quando um usuário abre um item por meio do Windows Explorer ou usa a caixa de diálogo de arquivo comum para abrir, salvar ou criar um arquivo, o Shell chama SHAddToRecentDocs em nome do aplicativo. Um aplicativo que tem uma interface do usuário personalizada para selecionar itens deve chamar SHAddToRecentDocs explicitamente para garantir estatísticas precisas. As chamadas duplicadas são contabilizados pelo sistema, portanto, não há risco de distorcer os dados fazendo isso.
Arquivos executáveis (.exe) são filtrados da lista de documentos usados recentemente no Windows XP e versões posteriores. Embora SHAddToRecentDocs aceite o caminho de um arquivo executável, esse arquivo não aparecerá na lista Itens Recentes .
As pastas também são aceitas por SHAddToRecentDocs, mas aparecem apenas na Lista de Atalhos para o botão da barra de tarefas do Windows Explorer. As pastas não aparecem na Lista de Atalhos de qualquer outro aplicativo.
Em determinados casos, SHAddToRecentDocs tenta registrar um aplicativo para manipular um tipo de arquivo que ele não está registrado para manipular. Isso ocorre nestas circunstâncias:
- Um aplicativo chama explicitamente SHAddToRecentDocs com um tipo de arquivo que não está registrado para manipular. Isso também se aplica a chamadas feitas para SHAddToRecentDocs pela caixa de diálogo de arquivo comum em nome do aplicativo, mas somente quando a caixa de diálogo é usada para abrir um arquivo, não quando ele é usado para salvar um.
- O usuário descarta um arquivo de um tipo que o aplicativo não está registrado para manipular no botão da barra de tarefas do aplicativo.
Um conjunto de requisitos deve ser atendido para que o registro seja realizado com êxito:
- O aplicativo deve ser registrado em HKEY_CLASSES_ROOT\Applications.
- Esse registro não pode incluir o valor NoOpenWith. Consulte Tipos de arquivo para obter mais detalhes sobre NoOpenWith.
- Esse registro não pode fornecer dados em uma subchave SupportedTypes . Consulte Tipos de arquivo para obter mais detalhes sobre a subchave SupportedTypes .
-
O arquivo executável do aplicativo não pode ser listado no valor KillList encontrado aqui:
HKEY_LOCAL_MACHINE Software Microsoft Windows CurrentVersion Explorer FileAssociation KillList
Nota Aplicativos de terceiros não devem modificar o valor KillList. Ele deve ser considerado como somente leitura. -
O registro HKEY_CLASSES_ROOT\Aplicativos do aplicativo deve ter um conjunto de verbos padrão definidos em um
HKEY_CLASSES_ROOT\Applications\ExampleApp.exe\shell subkey.
Se SHAddToRecentDocs estiver tentando o registro como resultado de um arrastar e soltar no botão da barra de tarefas, a subchave do shell será criada se ainda não existir, desde que o registro de aplicativo existente não contenha um valor NoOpenWith e o executável do aplicativo não esteja listado no valor KillList.
Suprimindo chamadas para SHAddToRecentDocs
Em versões do Windows anteriores ao Windows 7, um tipo de arquivo poderia definir o sinalizador FTA_NoRecentDocs para impedir que esse tipo de arquivo fosse adicionado à pasta Recente . Esse mecanismo também tem suporte no Windows 7 e posterior. Consulte Tipos de arquivo para obter mais informações.SHAddToRecentDocs rastreia estatísticas de uso de documentos por meio dos verbos que são invocados para acessar esses documentos. Verbos fornecidos por manipuladores IContextMenu registrados são rastreados, esses itens aparecem em Meus Documentos Recentes (Windows XP) e Itens Recentes (Windows Vista). No Windows 7, as pastas pai dos documentos aparecem na Lista de Atalhos para o botão da barra de tarefas do Windows Explorer. No entanto, os documentos acessados por meio desses verbos IContextMenu não aparecem no aplicativo Jump Listas. Para que esses itens apareçam na Lista de Atalhos de um aplicativo, um aplicativo deve chamar SHAddToRecentDocs explicitamente.
Antes do Windows 7, apenas o open verbo resultava em uma chamada para SHAddToRecentDocs. No Windows 7 e posterior, outros verbos também podem gerar estatísticas de uso. Essas informações são usadas para tornar os destinos de uma Lista de Atalhos mais completos e precisos.
No entanto, algumas classes de registros de associação de tipo de arquivo ou implementações individuais de IContextMenu não são apropriadas para esse tipo de acompanhamento. O ponto de acompanhamento de uso é gerar uma lista de itens que o usuário provavelmente desejará acessar novamente. Se um verbo específico,delete por exemplo, for inerentemente invocado em um item que o usuário não acessará novamente ou for uma ação secundária, como uma verificação de vírus em um arquivo, esse verbo não será apropriado para acompanhamento. As classes de tipo de arquivo devem remover-se desse acompanhamento por meio da entrada do Registro NoRecentDocs. NoRecentDocs é do tipo REG_SZ e não tem dados associados. Sua presença é tudo o que é necessário para impedir a chamada para SHAddToRecentDocs.
Por exemplo, extensões de menu de contexto e verbos estáticos registrados em HKEY_CLASSES_ROOT em classes como "*", "AllFileSystemObjects" ou "Folder" não devem ser rastreadas. Em casos como esses, a entrada NoRecentDocs é adicionada à raiz da chave de classe, conforme mostrado aqui para suprimir o acompanhamento de documentos iniciados por meio de qualquer verbo ou extensão registrada nessa classe:
HKEY_CLASSES_ROOT AllFileSystemObjects NoRecentDocs
A entrada NoRecentDocs é atribuída por padrão às *subchaves da classe , AllFileSystemObjects, Folder, Directory e DesktopBackground .
Implementações individuais de IContextMenu podem recusar o acompanhamento adicionando uma subchave NoRecentDocs ao registro do objeto COM (Component Object Model), em sua subchave shellex , conforme mostrado aqui:
HKEY_CLASSES_ROOT
CLSID
{093C7AAB-5E72-454f-A91D-CA1BC991FCEC}
shellex
NoRecentDocs
Essa subchave não está presente por padrão em nenhuma implementação de IContextMenu .
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows XP [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows 2000 Server [somente aplicativos da área de trabalho] |
| Plataforma de Destino | Windows |
| Cabeçalho | shlobj_core.h (inclua Shlobj.h) |
| Biblioteca | Shell32.lib |
| DLL | Shell32.dll (versão 4.0 ou posterior) |
| Conjunto de APIs | ext-ms-win-shell32-l1-2-2 (introduzido no Windows 10, versão 10.0.14393) |