Função SHSetKnownFolderPath (shlobj_core.h)

Artigo
03/02/2024

Redireciona uma pasta conhecida para um novo local.

Sintaxe

HRESULT SHSetKnownFolderPath(
  [in] REFKNOWNFOLDERID rfid,
  [in] DWORD            dwFlags,
  [in] HANDLE           hToken,
  [in] PCWSTR           pszPath
);

Parâmetros

[in] rfid

Tipo: REFKNOWNFOLDERID

Um GUID que identifica a pasta conhecida.

[in] dwFlags

Tipo: DWORD

0 ou o valor a seguir.

KF_FLAG_DONT_UNEXPAND

Se esse sinalizador for definido, partes do caminho referenciado por pszPath poderão ser representadas por cadeias de caracteres de ambiente, como %USERPROFILE%.

[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 do usuário atual da pasta. No entanto, talvez seja necessário atribuir um valor a hToken para as pastas que podem ter vários usuários, mas são tratadas como pertencentes a um único usuário. A pasta mais usada desse tipo é Documentos.

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. Confira 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 de SHSetKnownFolderPath definam locais de pasta (como a pasta Desktop ) para o Usuário Padrão. O perfil de usuário usuário padrão é 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] pszPath

Tipo: PCWSTR

Um ponteiro para o novo caminho da pasta. Essa é uma cadeia de caracteres Unicode terminada em nulo de comprimento MAX_PATH. Esse caminho não pode ter comprimento zero.

Retornar valor

Tipo: HRESULT

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

Código de retorno	Descrição
E_INVALIDARG	Entre outras coisas, esse valor pode indicar que o parâmetro rfid faz referência a um KNOWNFOLDERID que não está presente no sistema. Nem todos os valores KNOWNFOLDERID estão presentes em todos os sistemas. Use IKnownFolderManager::GetFolderIds para recuperar o conjunto de valores KNOWNFOLDERID para o sistema atual.

Comentários

Essa função substitui SHSetFolderPath. Essa função mais antiga agora é simplesmente um wrapper para SHSetKnownFolderPath.

O chamador dessa função deve ter privilégios de Administrador. 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.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2008 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	shlobj_core.h (inclua Shlobj.h)
DLL	Shell32.dll (versão 6.0.6000 ou posterior)