Função SHCreateDirectoryExA (shlobj_core.h)

  • Artigo

[Essa função está disponível por meio do Windows XP Service Pack 2 (SP2) e do Windows Server 2003. Ele pode estar alterado ou indisponível nas versões subsequentes do Windows.]

Cria uma nova pasta do sistema de arquivos, com atributos de segurança opcionais.

Sintaxe

int SHCreateDirectoryExA(
  [in, optional] HWND                      hwnd,
  [in]           LPCSTR                    pszPath,
  [in, optional] const SECURITY_ATTRIBUTES *psa
);

Parâmetros

[in, optional] hwnd

Digite: HWND

Um identificador de uma janela pai. Esse parâmetro poderá ser definido como NULL se nenhuma interface do usuário for exibida.

[in] pszPath

Tipo: LPCTSTR

Um ponteiro para uma cadeia de caracteres terminada em nulo especificando o caminho totalmente qualificado do diretório. Essa cadeia de caracteres tem o comprimento máximo de 248 caracteres, incluindo o caractere nulo de terminação.

[in, optional] psa

Tipo: const SECURITY_ATTRIBUTES*

Um ponteiro para uma estrutura SECURITY_ATTRIBUTES com o atributo de segurança do diretório. Defina esse parâmetro como NULL se nenhum atributo de segurança precisar ser definido.

Retornar valor

Tipo: int

Retorna ERROR_SUCCESS se tiver êxito. Se a operação falhar, outros códigos de erro poderão ser retornados, incluindo os listados aqui. Para valores não listados especificamente, consulte Códigos de erro do sistema.

Código de retorno Descrição
ERROR_BAD_PATHNAME
 O parâmetro pszPath foi definido como um caminho relativo.
ERROR_FILENAME_EXCED_RANGE
 O caminho apontado por pszPath é muito longo.
ERROR_PATH_NOT_FOUND
 O sistema não pode encontrar o caminho apontado por pszPath. O caminho pode conter uma entrada inválida.
ERROR_FILE_EXISTS
 O diretório existe.
ERROR_ALREADY_EXISTS
 O diretório existe.
ERROR_CANCELLED
 O usuário cancelou a operação.

Comentários

Essa função cria uma pasta do sistema de arquivos cujo caminho totalmente qualificado é fornecido pelo pszPath. Se uma ou mais pastas intermediárias não existirem, elas também serão criadas. SHCreateDirectoryEx também verifica se os arquivos estão visíveis. Se eles não estiverem visíveis, espere um destes procedimentos:

  • Se hwnd estiver definido como um identificador de janela válido, uma caixa de mensagem será exibida avisando ao usuário que ele ou ela pode não ser capaz de acessar os arquivos. Se o usuário optar por não continuar, a função retornará ERROR_CANCELLED.
  • Se hwnd estiver definido como NULL, nenhuma interface do usuário será exibida e a função retornará ERROR_CANCELLED.

Observação

O cabeçalho shlobj_core.h define SHCreateDirectoryEx 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 2000 Professional, 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

SHCreateDirectory