Função SHSetKnownFolderPath (shlobj_core.h)

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 referenciados 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 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] pszPath

Tipo: PCWSTR

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

Valor de retorno

Tipo: HRESULT

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

Observações

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.

Requirements

Consulte também

IKnownFolder::GetPath

IKnownFolder::SetPath

IKnownFolderManager::Redirect

Exemplo de pastas conhecidas

SHGetKnownFolderIDList

SHGetKnownFolderPath