Função SHSetFolderPathW (shlobj_core.h)

Artigo
11/20/2024

Deprecado. Atribui um novo caminho a uma pasta do sistema identificada pelo CSIDL.

Sintaxe

HRESULT SHSetFolderPathW(
  [in] int     csidl,
  [in] HANDLE  hToken,
  [in] DWORD   dwFlags,
  [in] LPCWSTR pszPath
);

Parâmetros

[in] csidl

Tipo: int

Um valor CSIDL que identifica a pasta cujo caminho deve ser definido. Somente pastas físicas são válidas. Se uma pasta virtual for especificada, essa função falhará.

Adicione o valor CSIDL_FLAG_DONT_UNEXPAND ao CSIDL para garantir que a cadeia de caracteres seja gravada no registro exatamente como fornecido. Se o sinalizador CSIDL_FLAG_DONT_UNEXPAND não estiver incluído, partes do caminho poderão ser substituídas por cadeias de caracteres de ambiente, como %USERPROFILE%.

[in] hToken

Tipo: HANDLE

Um token de acesso que pode ser usado para representar um usuário específico. Esse parâmetro geralmente é definido como NULL, nesse caso, 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 que 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. Consulte de Controle de Acesso para obter mais discussões sobre problemas de controle de acesso.

[in] dwFlags

Tipo: DWORD

Reservado. Deve ser definido como 0.

[in] pszPath

Tipo: LPCTSTR

Um ponteiro para uma cadeia de caracteres de comprimento terminada em nulo MAX_PATH que contém o novo caminho da pasta. Esse valor não pode ser NULL e a cadeia de caracteres não pode ter tamanho zero.

Valor de retorno

Tipo: HRESULT

Retorna códigos de HRESULT padrão, incluindo o seguinte:

Código de retorno	Descrição
S_OK	O caminho da pasta foi atualizado com êxito.
E_INVALIDARG	Várias condições de erro causam o retorno desse valor, incluindo o seguinte: O valor csidl não é válido. O valor csidl não se refere a uma pasta virtual. O valor csidl não se refere a uma pasta do sistema. O valor csidl refere-se a uma pasta que não pode ser renomeada ou movida. O valor dwFlags não é 0 (zero). O valor pszPath é NULL. A cadeia de caracteres apontada por pszPath valor é uma cadeia de caracteres vazia ("") de comprimento zero.

Código de retorno

Descrição

S_OK

O caminho da pasta foi atualizado com êxito.

E_INVALIDARG

Várias condições de erro causam o retorno desse valor, incluindo o seguinte:

O valor csidl não é válido.
O valor csidl não se refere a uma pasta virtual.
O valor csidl não se refere a uma pasta do sistema.
O valor csidl refere-se a uma pasta que não pode ser renomeada ou movida.
O valor dwFlags não é 0 (zero).
O valor pszPath é NULL.
A cadeia de caracteres apontada por pszPath valor é uma cadeia de caracteres vazia ("") de comprimento zero.

Observações

Observação Do Windows Vista, essa função é apenas um wrapper para SHSetKnownFolderPath. O valor CSIDL é convertido em seu KNOWNFOLDERID associado e SHSetKnownFolderPath é chamado. Novos aplicativos devem usar o sistema de pastas conhecido em vez do sistema CSIDL mais antigo, que tem suporte apenas para compatibilidade com versões anteriores.

SHSetFolderPath não é exportado pelo nome de Shell32.dll. Para usar a função, você deve chamar GetProcAddress com ordinal 231 para SHSetFolderPathA (para cadeias de caracteres ANSI) ou ordinal 232 para SHSetFolderPathW (para cadeias de caracteres Unicode) para obter um ponteiro de função.

É recomendável que os caminhos sejam expressos como cadeias de caracteres Unicode porque os nomes de pasta podem conter caracteres Unicode não expressíveis no ANSI.

Nota

O cabeçalho shlobj_core.h define SHSetFolderPath como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows XP [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows Server 2003 [somente aplicativos da área de trabalho]
da Plataforma de Destino	Windows
cabeçalho	shlobj_core.h (inclua Shlobj.h, Shlobj_core.h)
biblioteca	Shell32.lib
de DLL	Shell32.dll (versão 5.0 ou posterior)

Consulte também

IKnownFolder::SetPath

Compartilhar via