Função SHGetKnownFolderItem (shlobj_core.h)

Recupera um objeto IShellItem que representa uma pasta conhecida.

Sintaxe

HRESULT SHGetKnownFolderItem(
  [in]  REFKNOWNFOLDERID  rfid,
  [in]  KNOWN_FOLDER_FLAG flags,
  [in]  HANDLE            hToken,
  [in]  REFIID            riid,
  [out] void              **ppv
);

Parameters

[in] rfid

Tipo: REFKNOWNFOLDERID

Uma referência ao KNOWNFOLDERID, um GUID que identifica a pasta que contém o item.

[in] flags

Tipo: KNOWN_FOLDER_FLAG

Sinalizadores que especificam opções especiais usadas na recuperação da pasta conhecida IShellItem. Esse valor pode ser KF_FLAG_DEFAULT; caso contrário, um ou mais dos valores KNOWN_FOLDER_FLAG .

[in] hToken

Tipo: HANDLE

Um token de acesso usado para representar um usuário específico. Esse parâmetro geralmente é definido como NULL, caso em que a função tenta acessar a instância atual do usuário da pasta. No entanto, talvez seja necessário atribuir um valor ao hToken para as pastas que podem ter vários usuários, mas que são tratadas como pertencentes a um único usuário. A pasta mais usada desse tipo é Documents.

O aplicativo de chamada é responsável pela representação correta quando hToken não é nulo. Ele deve ter privilégios de segurança apropriados para o usuário específico, incluindo TOKEN_QUERY e TOKEN_IMPERSONATE, e o hive do registro do usuário deve estar montado no momento. Consulte o Controle de Acesso para obter mais discussões sobre problemas de controle de acesso.

Atribuir ao parâmetro hToken um valor de -1 indica o Usuário Padrão. Isso permite que os clientes do SHSetKnownFolderPath definam locais de pasta (como a pasta Desktop ) para o Usuário Padrão. O perfil de usuário padrão do usuário é duplicado quando qualquer nova conta de usuário é criada e inclui pastas especiais, como Documentos e Área de Trabalho. Todos os itens adicionados à pasta Usuário Padrão também aparecem em qualquer nova conta de usuário. Observe que o acesso às pastas de usuário padrão requer privilégios de administrador.

[in] riid

Tipo: REFIID

Uma referência à IID da interface que representa o item, geralmente IID_IShellItem ou IID_IShellItem2.

[out] ppv

Tipo: void**

Quando esse método é retornado, contém o ponteiro de interface solicitado no riid.

Valor de devolução

Tipo: HRESULT

Retorna S_OK se tiver êxito ou um valor de erro, incluindo o seguinte:

Observações

Para chamar essa função em pastas conhecidas públicas, o chamador deve ter privilégios de Administrador. Para pastas conhecidas por usuário, o chamador requer apenas privilégios de usuário.

Algumas das pastas conhecidas, por exemplo, a pasta Documentos , são por usuário. Cada usuário tem um caminho diferente para a pasta Documentos . Se hToken for NULL, a API tentará acessar a instância do aplicativo de chamada da pasta, que é a do usuário atual. Se hToken for um token de usuário válido, a API tentará representar o usuário usando esse token e tentará acessar a instância desse usuário.

Essa função não pode ser chamada em pastas do tipo KF_CATEGORY_FIXED e KF_CATEGORY_VIRTUAL.

Para chamar essa função em uma pasta do tipo KF_CATEGORY_COMMON, o aplicativo de chamada deve estar em execução com privilégios elevados.

Requirements

Consulte também

IKnownFolder::GetPath

IKnownFolderManager::Redirect

Exemplo de pastas conhecidas

SHCreateItemInKnownFolder

SHGetKnownFolderIDList

SHGetKnownFolderPath