Função SHSetFolderPathA (shlobj_core.h)

  • Artigo

Preterido. Atribui um novo caminho a uma pasta do sistema identificada por seu CSIDL.

Sintaxe

HRESULT SHSetFolderPathA(
  [in] int    csidl,
  [in] HANDLE hToken,
  [in] DWORD  dwFlags,
  [in] LPCSTR 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 conforme 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, 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.

[in] dwFlags

Tipo: DWORD

Reservado. Deve ser definido como 0.

[in] pszPath

Tipo: LPCTSTR

Um ponteiro para uma cadeia de caracteres terminada em nulo de comprimento 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 comprimento zero.

Retornar valor

Tipo: HRESULT

Retorna códigos 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 de pszPath é NULL.
  • A cadeia de caracteres apontada pelo valor pszPath é uma cadeia de caracteres vazia ("") de comprimento zero.

Comentários

Nota A partir 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.

Observação

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. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

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

Confira também

IKnownFolder::SetPath