Compartilhar via

Função CreateDirectory2A (fileapi.h)

Cria um novo diretório. Se o sistema de arquivos subjacente der suporte à segurança em arquivos e diretórios, a função aplicará um descritor de segurança especificado ao novo diretório.

Para especificar um diretório de modelo, use a função CreateDirectoryEx .

Para executar essa operação como uma operação transacionada, use a função CreateDirectoryTransacted .

Sintaxe

HANDLE CreateDirectory2A(
  LPCSTR                lpPathName,
  DWORD                 dwDesiredAccess,
  DWORD                 dwShareMode,
  DIRECTORY_FLAGS       DirectoryFlags,
  LPSECURITY_ATTRIBUTES lpSecurityAttributes
);

Parâmetros

lpPathName

O caminho do diretório a ser criado.

Por padrão, o nome é limitado a MAX_PATH caracteres. Para estender esse limite para 32.767 caracteres de largura, acrescente "\\?\" ao caminho. Para obter mais informações, veja Naming Files, Paths, and Namespaces (Nomenclatura de Ficheiros, Caminhos e Espaços de Nomes).

Dica

Você pode aceitar para remover a limitação de MAX_PATH sem acrescentar "\\?\". Consulte a seção "Limitação máxima do comprimento do caminho" de Arquivos de Nomenclatura, Caminhos e Namespaces para obter detalhes.

dwDesiredAccess

O valor ACCESS_MASK que expressa o tipo de acesso que o chamador requer para o diretório. O conjunto de sinalizadores dwDesiredAccess definidos pelo sistema determina os seguintes objetos de arquivo de diretório de direitos de acesso específicos:

Valor Significado
FILE_LIST_DIRECTORY Os arquivos no diretório podem ser listados.
FILE_TRAVERSE O diretório pode ser percorrido: ou seja, pode fazer parte do nome do caminho de um arquivo.
SINCRONIZAR O identificador retornado pode ser aguardado para sincronizar com a conclusão de uma operação de E/S. Se o identificador não tiver sido aberto para E/S síncrona, esse valor será ignorado.

dwShareMode

O tipo de acesso de compartilhamento que o chamador gostaria de usar no arquivo, como zero, ou como um ou uma combinação dos seguintes valores:

Valor Significado
0
0x00000000		 Impede que outros processos abram um arquivo ou dispositivo se solicitarem acesso de exclusão, leitura ou gravação.
FILE_SHARE_READ
0x00000001		 Permite que as operações abertas subsequentes em um arquivo ou dispositivo solicitem acesso de leitura. Caso contrário, outros processos não poderão abrir o arquivo ou o dispositivo se solicitarem acesso de leitura. Se esse sinalizador não for especificado, mas o arquivo ou dispositivo tiver sido aberto para acesso de leitura, a função falhará.
FILE_SHARE_WRITE
0x00000002		 Habilita operações abertas subsequentes em um arquivo ou dispositivo para solicitar acesso de gravação. Caso contrário, outros processos não poderão abrir o arquivo ou o dispositivo se solicitarem acesso de gravação. Se esse sinalizador não for especificado, mas o arquivo ou dispositivo tiver sido aberto para acesso de gravação ou tiver um mapeamento de arquivo com acesso de gravação, a função falhará.
FILE_SHARE_DELETE
0x00000004		 Habilita operações abertas subsequentes em um arquivo ou dispositivo para solicitar acesso de exclusão. Caso contrário, outros processos não poderão abrir o arquivo ou o dispositivo se solicitarem o acesso de exclusão. Se esse sinalizador não for especificado, mas o arquivo ou dispositivo tiver sido aberto para exclusão de acesso, a função falhará.

Nota: Excluir o acesso permite operações de exclusão e renomeação.

DirectoryFlags

Esse parâmetro pode conter combinações de DIRECTORY_FLAGS.

Valor Significado
DIRECTORY_FLAGS_DISALLOW_PATH_REDIRECTS
0x00000001		 Impedir que lpPathName seja redirecionado por pontos de nova análise ou links simbólicos.

lpSecurityAttributes

Um ponteiro para uma estrutura SECURITY_ATTRIBUTES . O membro lpSecurityDescriptor da estrutura especifica um descritor de segurança para o novo diretório. Se lpSecurityAttributes for NULL, o diretório obterá um descritor de segurança padrão. As ACLs no descritor de segurança padrão para um diretório são herdadas de seu diretório pai.

O sistema de arquivos de destino deve dar suporte à segurança em arquivos e diretórios para que esse parâmetro tenha um efeito. (Isso é indicado quando GetVolumeInformation retorna FS_PERSISTENT_ACLS.)

Valor de retorno

Se a função for bem-sucedida, o valor retornado não será zero.

Se a função falhar, o valor retornado será INVALID_HANDLE_VALUE. Para obter informações de erro estendidas, chame GetLastError.

Os possíveis erros incluem o seguinte:

Código de retorno Descrição
ERROR_ALREADY_EXISTS O diretório especificado já existe.
ERROR_PATH_NOT_FOUND Um ou mais diretórios intermediários não existem; essa função criará apenas o diretório final no caminho.
ERROR_PATH_REDIRECTED LpNewDirectory foi redirecionado por pontos de nova análise e/ou links simbólicos.

Observações

Alguns sistemas de arquivos, como o sistema de arquivos NTFS, dão suporte à compactação ou criptografia para arquivos e diretórios individuais. Em volumes formatados para esse sistema de arquivos, um novo diretório herda os atributos de compactação e criptografia de seu diretório pai.

Um aplicativo pode obter um identificador para um diretório chamando CreateFile com o sinalizador FILE_FLAG_BACKUP_SEMANTICS definido. Para obter um exemplo de código, consulte CreateFile.

Para dar suporte a funções de herança que consultam o descritor de segurança desse objeto pode determinar heuristicamente e relatar que a herança está em vigor. Consulte Propagação Automática de ACEs Herdáveis para obter mais informações.

Essa função é compatível com as seguintes tecnologias:

Tecnologia Suportado
Protocolo SMB (Bloco de Mensagens do Servidor) 3.0 Sim
TFO (Failover Transparente) do SMB 3.0 Sim
SMB 3.0 com Compartilhamentos de Arquivos de Expansão (SO) Sim
Sistema de Arquivos de Volume Compartilhado de Cluster (CsvFS) Sim
ReFS (Sistema de Arquivos Resiliente) Sim

Observação

O fileapi.h cabeçalho define CreateDirectory2 como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante do 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.

Exemplos

O exemplo a seguir cria um novo diretório com a função CreateDirectory2 . O novo diretório é criado com os direitos de acesso FILE_LIST_DIRECTORY e SYNCHRONIZE . O novo diretório também é criado com o modo de compartilhamento FILE_SHARE_READ , que permite que outros processos abram o diretório para acesso de leitura.

// THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF 
// ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO 
// THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A 
// PARTICULAR PURPOSE. 
// 
// Copyright (C) Microsoft. All rights reserved 
#include <Windows.h>
#include <stdio.h>
#include <strsafe.h>

int main(int argc, wchar_t* argv[])
{
    WCHAR filePath[MAX_PATH] = { 0 };

    // Create a directory to put a file into, that can't be deleted
    // and redirected before this handle is closed.
    HANDLE hDirectory = CreateDirectory2(argv[1],
        FILE_LIST_DIRECTORY | SYNCHRONIZE,
        FILE_SHARE_READ,
        DIRECTORY_FLAGS_NONE,
        NULL,
        NULL);
    if (hDirectory == INVALID_HANDLE_VALUE)
    {
        // Handle the error.
        printf("CreateDirectory2 failed (%d)\n", GetLastError());
        return (1);
    }

    StringCchPrintf(filePath,
        ARRAYSIZE(filePath),
        L"%ws\\example.test",
        argv[1]);

    HANDLE hFile = CreateFile3(filePath,
        GENERIC_ALL,
        FILE_SHARE_READ,
        CREATE_ALWAYS,
        NULL);
    if (hFile == INVALID_HANDLE_VALUE)
    {
        // Handle the error.
        CloseHandle(hDirectory);
        printf("CreateFile3 failed (%d)\n", GetLastError());
        return (1);
    }

    CloseHandle(hFile);
    CloseHandle(hDirectory);
    return (0);
}

Para obter exemplos adicionais, consulte Recuperar e alterar atributos de arquivo.

Requisitos

Requisito Valor
de cliente com suporte mínimo Windows 11 24H2 [aplicativos da área de trabalho | Aplicativos UWP]
servidor com suporte mínimo Windows Server 2025 [aplicativos da área de trabalho | Aplicativos UWP]
cabeçalho fileapi.h (inclua Windows.h)
Biblioteca Kernel32.lib
de DLL Kernel32.dll

Consulte também

CreateFile3

DeleteFile2

RemoveDirectory2

  • Last updated on