Função SHCreateDirectoryExA (shlobj_core.h)

Artigo
11/20/2024

[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

Tipo: HWND

Um identificador para uma janela pai. Esse parâmetro pode 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 comprimento máximo de 248 caracteres, incluindo o caractere nulo de encerramento.

[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.

Valor de retorno

Tipo: int

Retorna ERROR_SUCCESS se bem-sucedido. 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.

Observações

Essa função cria uma pasta do sistema de arquivos cujo caminho totalmente qualificado é fornecido por 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 dos seguintes:

Se for 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 prosseguir, 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.

Nota

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. 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 2000 Professional, 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

SHCreateDirectory

Compartilhar via