Compartilhar via

Função NtCreateNamedPipeFile

  • Artigo

Cria e abre o identificador de fim de servidor da primeira instância de um pipe nomeado específico ou outra instância de um pipe nomeado existente. A função retorna um identificador que pode ser usado para acessar o pipe.

Sintaxe

NTSTATUS NtCreateNamedPipeFile(
  [out]          PHANDLE            FileHandle,
  [in]           ULONG              DesiredAccess,
  [in]           POBJECT_ATTRIBUTES ObjectAttributes,
  [out]          PIO_STATUS_BLOCK   IoStatusBlock,
  [in]           ULONG              ShareAccess,
  [in]           ULONG              CreateDisposition,
  [in]           ULONG              CreateOptions,
  [in]           ULONG              NamedPipeType,
  [in]           ULONG              ReadMode,
  [in]           ULONG              CompletionMode,
  [in]           ULONG              MaximumInstances,
  [in]           ULONG              InboundQuota,
  [in]           ULONG              OutboundQuota,
  [in, optional] PLARGE_INTEGER     DefaultTimeout
);

Parâmetros

FileHandle [out]

Ponteiro para uma variável que recebe o identificador de arquivo se a chamada for bem-sucedida.

DesiredAccess [in]

Uma máscara de bits de sinalizadores que especifica o tipo de acesso ao arquivo ou diretório exigido pelo chamador. Esse conjunto de sinalizadores DesiredAccess definidos pelo sistema determina os direitos de acesso específicos a seguir para objetos de arquivo.

Sinalizador Descrição
Delete (excluir) O arquivo pode ser excluído.
FILE_READ_DATA Os dados podem ser lidos no arquivo.
FILE_READ_ATTRIBUTES Os sinalizadores FileAttributes, descritos abaixo, podem ser lidos.
FILE_READ_EA Os EAs (atributos estendidos) associados ao arquivo podem ser lidos.
READ_CONTROL A ACL (lista de controle de acesso) e as informações de propriedade associadas ao arquivo podem ser lidas.
FILE_WRITE_DATA Os dados podem ser gravados no arquivo.
FILE_WRITE_ATTRIBUTES Os sinalizadores FileAttributes podem ser gravados.
FILE_WRITE_EA Os EAs associados ao arquivo podem ser gravados.
FILE_APPEND_DATA Os dados podem ser acrescentados ao arquivo.
WRITE_DAC A DACL (lista de controle de acesso discricionário) associada ao arquivo pode ser gravada.
WRITE_OWNER As informações de propriedade associadas ao arquivo podem ser gravadas.
SYNCHRONIZE O chamador pode sincronizar a conclusão de uma operação de E/S aguardando que o FileHandle retornado seja definido como o estado Sinalizado. Esse sinalizador deverá ser definido se o sinalizador CreateOptionsFILE_SYNCHRONOUS_IO_ALERT ou FILE_SYNCHRONOUS_IO_NONALERT for definido.
FILE_EXECUTE Os dados podem ser lidos na memória do arquivo usando E/S de paginação do sistema.

Como alternativa, para qualquer objeto de arquivo que não represente um diretório, você pode especificar um ou mais dos seguintes sinalizadores genéricos de ACCESS_MASK . Os sinalizadores STANDARD_RIGHTS_XXX são valores predefinidos do sistema que são usados para impor a segurança em objetos do sistema. Você também pode combinar esses sinalizadores genéricos com sinalizadores adicionais da tabela anterior.

Acesso desejado a valores de arquivo Mapeia para sinalizadores DesiredAccess
GENERIC_READ STANDARD_RIGHTS_READ, FILE_READ_DATA, FILE_READ_ATTRIBUTES, FILE_READ_EA, SYNCHRONIZE.
GENERIC_WRITE STANDARD_RIGHTS_WRITE, FILE_WRITE_DATA, FILE_WRITE_ATTRIBUTES, FILE_WRITE_EA, FILE_APPEND_DATA, SYNCHRONIZE.
GENERIC_EXECUTE STANDARD_RIGHTS_EXECUTE, SYNCHRONIZE, FILE_READ_ATTRIBUTES, FILE_EXECUTE.

Para diretórios (o FILE_DIRECTORY_FILE sinalizador CreateOptions está definido), você pode especificar um ou mais dos sinalizadores de ACCESS_MASK a seguir, que você também pode combinar com quaisquer sinalizadores compatíveis descritos anteriormente.

Acesso desejado aos valores de diretório Descrição
FILE_LIST_DIRECTORY Os arquivos no diretório podem ser listados.
FILE_TRAVERSE O diretório pode ser percorrido; ou seja, ele pode fazer parte do nome do caminho de um arquivo.

Os FILE_READ_DATAsinalizadores , FILE_WRITE_DATAFILE_EXECUTE, e FILE_APPEND_DATADesiredAccess são incompatíveis com a criação ou abertura de um arquivo de diretório.

ObjectAttributes [in]

Ponteiro para uma OBJECT_ATTRIBUTES estrutura já inicializada pela rotina InitializeObjectAttributes . Se o chamador estiver em execução no contexto do processo do sistema, esse parâmetro poderá ser NULL. Caso contrário, o chamador deve definir o OBJ_KERNEL_HANDLE atributo na chamada como InitializeObjectAttributes.

Os membros dessa estrutura para um objeto de arquivo incluem o seguinte:

Membro Valor
Comprimento do ULONG O número de bytes dos dados ObjectAttributes fornecidos . Esse valor deve ser pelo menos sizeof(OBJECT_ATTRIBUTES).
PUNICODE_STRING ObjectName Ponteiro para uma cadeia de caracteres Unicode em buffer que contém o nome do arquivo a ser criado ou aberto. Esse valor deve ser uma especificação de arquivo totalmente qualificada, a menos que seja o nome de um arquivo relativo ao diretório especificado por RootDirectory. Por exemplo, "\Device\Floppy1\myfile.dat" ou "?? \B:\myfile.dat" pode ser a especificação de arquivo totalmente qualificada, desde que o driver de unidade de disco disquete e o sistema de arquivos de sobreposição já estejam carregados. (Observação: "??" substitui "\DosDevices" como o nome do namespace do objeto Win32. "\DosDevices" ainda funciona, mas "??" é traduzido mais rapidamente pelo gerenciador de objetos.)
HANDLE RootDirectory Identificador opcional para um diretório que foi obtido por uma chamada anterior para NtCreateNamedPipeFile. Se esse valor for NULL, o membro ObjectName deverá ser uma especificação de arquivo totalmente qualificada que inclua o caminho completo para o arquivo de destino. Se esse valor não for NULL, o membro ObjectName especificará um nome de arquivo relativo a esse diretório.
PSECURITY_DESCRIPTOR SecurityDescriptor Descritor de segurança opcional a ser aplicado a um arquivo. As ACLs especificadas por esse descritor de segurança só são aplicadas ao arquivo quando ele é criado. Se o valor for NULL quando um arquivo for criado, a ACL colocada no arquivo dependerá do sistema de arquivos; A maioria dos sistemas de arquivos propaga alguma parte dessa ACL do arquivo de diretório pai combinado com a ACL padrão do chamador.
Atributos ULONG Um conjunto de sinalizadores que controla os atributos de objeto de arquivo. Se o chamador estiver em execução no contexto do processo do sistema, esse parâmetro poderá ser zero. Caso contrário, o chamador deve definir o OBJ_KERNEL_HANDLE sinalizador . Opcionalmente, o chamador também pode definir o OBJ_CASE_INSENSITIVE sinalizador , que indica que o código de pesquisa de nome deve ignorar o caso de ObjectName em vez de executar uma pesquisa de correspondência exata.

IoStatusBlock [out]

Ponteiro para uma variável do tipo IO_STATUS_BLOCK que recebe o status de conclusão final e informações sobre a operação solicitada. No retorno de NtCreateNamedPipeFile, o membro Information da variável contém um dos seguintes valores:

  • FILE_CREATED
  • FILE_OPENED
  • FILE_OVERWRITTEN
  • FILE_SUPERSEDED
  • FILE_EXISTS
  • FILE_DOES_NOT_EXIST

ShareAccess [in]

Especifica o tipo de acesso de compartilhamento ao arquivo que o chamador gostaria, como zero, ou um, ou uma combinação dos sinalizadores a seguir. Para solicitar acesso exclusivo, defina esse parâmetro como zero. Para ajudá-lo a evitar erros de violação de compartilhamento, especifique todos os sinalizadores de acesso de compartilhamento a seguir.

Sinalizadores do ShareAccess Descrição
FILE_SHARE_READ O arquivo pode ser aberto para acesso de leitura por chamadas de criação de arquivo de outros threads.
FILE_SHARE_WRITE O arquivo pode ser aberto para acesso de gravação por chamadas de criação de arquivo de outros threads.
FILE_SHARE_DELETE O arquivo pode ser aberto para excluir o acesso por chamadas de criação de arquivo de outros threads.

Drivers de dispositivo e drivers intermediários geralmente definem ShareAccess como zero, o que fornece ao chamador acesso exclusivo ao arquivo aberto.

CreateDisposition [in]

Valor que determina como o arquivo deve ser tratado quando o arquivo já existe. CreateDisposition pode ser um dos seguintes:

Valor Descrição
FILE_SUPERSEDE Se o arquivo já existir, substitua-o pelo arquivo fornecido. Se ele não existir, crie o arquivo fornecido.
FILE_CREATE Se o arquivo já existir, falhe na solicitação e não crie ou abra o arquivo fornecido. Se ele não existir, crie o arquivo fornecido.
FILE_OPEN Se o arquivo já existir, abra-o em vez de criar um novo arquivo. Se ele não existir, falhe na solicitação e não crie um novo arquivo.
FILE_OPEN_IF Se o arquivo já existir, abra-o. Se ele não existir, crie o arquivo fornecido.
FILE_OVERWRITE Se o arquivo já existir, abra-o e substitua-o. Se ele não existir, falhe na solicitação.
FILE_OVERWRITE_IF Se o arquivo já existir, abra-o e substitua-o. Se ele não existir, crie o arquivo fornecido.

CreateOptions [in]

Especifica as opções a serem aplicadas ao criar ou abrir o arquivo, como uma combinação compatível dos sinalizadores a seguir.

Sinalizador CreateOptions Descrição
FILE_DIRECTORY_FILE (0x00000001) O arquivo que está sendo criado ou aberto é um arquivo de diretório. Com esse sinalizador, o parâmetro Disposition deve ser definido como um de FILE_CREATE, FILE_OPENou FILE_OPEN_IF. Os sinalizadores CreateOptions compatíveis com esse sinalizador são os seguintes: FILE_SYNCHRONOUS_IO_ALERT, FILE_SYNCHRONOUS_IO_NONALERT, FILE_WRITE_THROUGH, FILE_OPEN_FOR_BACKUP_INTENTe FILE_OPEN_BY_FILE_ID.
FILE_WRITE_THROUGH (0x00000002) Os serviços do sistema, os sistemas de arquivos e os drivers que gravam dados no arquivo devem realmente transferir os dados para o arquivo antes que qualquer operação de gravação solicitada seja considerada concluída.
FILE_SEQUENTIAL_ONLY (0x00000004) Todos os acessos ao arquivo serão sequenciais.
FILE_NO_INTERMEDIATE_BUFFERING (0x00000008) O arquivo não pode ser armazenado em cache ou armazenado em buffer nos buffers internos de um driver. Esse sinalizador é incompatível com o sinalizador DesiredAccessFILE_APPEND_DATA .
FILE_SYNCHRONOUS_IO_ALERT (0x00000010) Todas as operações no arquivo são executadas de forma síncrona. Qualquer espera em nome do chamador está sujeita ao encerramento prematuro de alertas. Esse sinalizador também faz com que o sistema de E/S mantenha o contexto de posição do arquivo. Se esse sinalizador estiver definido, o sinalizador DesiredAccessSYNCHRONIZE também deverá ser definido para que o Gerenciador de E/S use o objeto de arquivo como um objeto de sincronização.
FILE_SYNCHRONOUS_IO_NONALERT (0x00000020) Todas as operações no arquivo são executadas de forma síncrona. As esperas no sistema para sincronizar a fila de E/S e a conclusão não estão sujeitas a alertas. Esse sinalizador também faz com que o sistema de E/S mantenha o contexto de posição do arquivo. Se esse sinalizador estiver definido, o sinalizador DesiredAccessSYNCHRONIZE também deverá ser definido para que o Gerenciador de E/S use o objeto de arquivo como um objeto de sincronização.
FILE_NON_DIRECTORY_FILE (0x00000040) O arquivo que está sendo aberto não deve ser um arquivo de diretório ou essa chamada falha. O objeto de arquivo que está sendo aberto pode representar um arquivo de dados; um dispositivo lógico, virtual ou físico; ou um volume.
FILE_CREATE_TREE_CONNECTION (0x00000080) Crie uma conexão de árvore para esse arquivo para abri-lo pela rede.
FILE_COMPLETE_IF_OPLOCKED (0x00000100) Conclua essa operação imediatamente com um código de êxito alternativo se o arquivo de destino estiver bloqueado, em vez de bloquear o thread do chamador. Se o arquivo estiver oplocked, outro chamador já terá acesso ao arquivo pela rede.
FILE_NO_EA_KNOWLEDGE (0x00000200) Se os atributos estendidos em um arquivo existente que está sendo aberto indicarem que o chamador deve entender os atributos estendidos para interpretar corretamente o arquivo, falhe essa solicitação porque o chamador não entende como lidar com atributos estendidos.
FILE_OPEN_REMOTE_INSTANCE (0x00000400) Reservado para uso do sistema; não use.
FILE_RANDOM_ACCESS (0x00000800) Os acessos ao arquivo podem ser aleatórios, portanto, nenhuma operação sequencial de leitura antecipada deve ser executada no arquivo por sistemas de arquivos ou pelo sistema operacional.
FILE_DELETE_ON_CLOSE (0x00001000) Exclua o arquivo quando o último identificador para ele for passado para FltClose.
FILE_OPEN_BY_FILE_ID (0x00002000) O arquivo está sendo aberto pela ID. O nome do arquivo contém o nome de um dispositivo e uma ID de 64 bits a ser usada para abrir o arquivo.
FILE_OPEN_FOR_BACKUP_INTENT (0x000004000) O arquivo está sendo aberto para intenção de backup; Portanto, o sistema deve verificar determinados direitos de acesso e conceder ao chamador os acessos apropriados ao arquivo antes de verificar a entrada DesiredAccess no descritor de segurança do arquivo.
FILE_NO_COMPRESSION (0x00008000) Suprima a herança de FILE_ATTRIBUTE_COMPRESSED do diretório pai. Isso permite a criação de um arquivo não compactado em um diretório marcado como compactado.
FILE_OPEN_REQUIRING_OPLOCK (0x00010000) O arquivo está sendo aberto e um bloqueio oportunista (oplock) no arquivo está sendo solicitado como uma única operação atômica. O sistema de arquivos verifica se há oplocks antes de executar a operação de criação e a operação de criação falhará com um código de retorno de se a operação de STATUS_CANNOT_BREAK_OPLOCK criação interromper um oplock existente. Esse sinalizador está disponível nos sistemas operacionais Windows 7, Windows Server 2008 R2 e posteriores.
FILE_DISALLOW_EXCLUSIVE (0x00020000) Ao abrir um arquivo existente, se FILE_SHARE_READ não for especificado e as verificações de acesso do sistema de arquivos não concederem ao chamador acesso de gravação ao arquivo, não será possível abri-lo com STATUS_ACCESS_DENIED. Esse era o comportamento padrão antes do Windows 7.
FILE_SESSION_AWARE (0x00040000) O arquivo ou dispositivo está sendo aberto com reconhecimento de sessão. Se esse sinalizador não for especificado, os dispositivos por sessão (como um dispositivo que usa o Redirecionamento USB RemoteFX) não poderão ser abertos por processos em execução na sessão 0. Esse sinalizador não tem efeito para os chamadores que não estão na sessão 0. Esse sinalizador tem suporte apenas em edições de servidor do Windows. Não há suporte para esse sinalizador antes de Windows Server 2012.
FILE_RESERVE_OPFILTER (0x00100000) Esse sinalizador permite que um aplicativo solicite um bloqueio oportunista de filtro (oplock) para impedir que outros aplicativos sejam violações de compartilhamento. Se já houver identificadores abertos, a solicitação de criação falhará com STATUS_OPLOCK_NOT_GRANTED.
FILE_OPEN_REPARSE_POINT (0x00200000) Abra um arquivo com um ponto de nova análise e ignore o processamento normal de ponto de nova análise para o arquivo. Para obter mais informações, consulte a seção Comentários a seguir.
FILE_OPEN_NO_RECALL (0x00400000) Instrui todos os filtros que executam armazenamento offline ou virtualização a não se lembrarem do conteúdo do arquivo como resultado dessa abertura.
FILE_OPEN_FOR_FREE_SPACE_QUERY (0x00800000) Esse sinalizador instrui o sistema de arquivos a capturar o usuário associado ao thread de chamada. Todas as chamadas subsequentes para FltQueryVolumeInformation ou ZwQueryVolumeInformationFile usando o identificador retornado assumirão que o usuário capturado, em vez do usuário chamador no momento, para fins de calcular o espaço livre disponível para o chamador. Isso se aplica aos seguintes valores FsInformationClass : FileFsSizeInformation, FileFsFullSizeInformatione FileFsFullSizeInformationEx.

NamedPipeType [in]

Tipo de pipe nomeado a ser criado (tipo de byte ou tipo de mensagem).

ReadMode [in]

Modo no qual ler o pipe (tipo de byte ou tipo de mensagem).

CompletionMode [in]

Especifica como a operação deve ser concluída.

MaximumInstances [in]

Número máximo de instâncias simultâneas do pipe nomeado.

InboundQuota [in]

Especifica a cota de pool reservada para gravações no lado de entrada do pipe nomeado.

OutboundQuota [in]

Especifica a cota de pool reservada para gravações no lado de entrada do pipe nomeado.

DefaultTimeout [in, opcional]

Um ponteiro opcional para um valor de tempo limite que será usado se um valor de tempo limite não for especificado ao aguardar uma instância de um pipe nomeado.

Retornos

O valor da função é o status final da operação de criação/abertura.

Comentários

Para criar uma instância de um pipe nomeado, o usuário deve ter FILE_CREATE_PIPE_INSTANCE acesso ao objeto de pipe nomeado. Se um novo pipe nomeado estiver sendo criado, a ACL (lista de controle de acesso) do parâmetro de atributos de segurança definirá o controle de acesso discricionário para o pipe nomeado.

Todas as instâncias de um pipe nomeado devem especificar o mesmo tipo de pipe (tipo de byte ou tipo de mensagem), acesso de pipe (duplex, entrada ou saída), contagem de instâncias e valor de tempo limite. Se valores diferentes forem usados, essa função falhará e GetLastError retornará ERROR_ACCESS_DENIED.

Um processo de cliente se conecta a um pipe nomeado usando a função CreateFile ou CallNamedPipe . O lado do cliente de um pipe nomeado começa no modo byte, mesmo que o lado do servidor esteja no modo de mensagem. Para evitar problemas ao receber dados, defina o lado do cliente como o modo de mensagem também. Para alterar o modo do pipe, o cliente de pipe deve abrir um pipe somente leitura com acesso GENERIC_READ e FILE_WRITE_ATTRIBUTES .

O servidor de pipe não deve executar uma operação de leitura de bloqueio até que o cliente de pipe seja iniciado. Caso contrário, uma condição de corrida pode ocorrer. Isso normalmente ocorre quando o código de inicialização, como o tempo de execução C, precisa bloquear e examinar identificadores herdados.

Sempre que um pipe nomeado é criado, o sistema cria os buffers de entrada e/ou saída usando o pool nãopagado, que é a memória física usada pelo kernel. O número de instâncias de pipe (bem como objetos como threads e processos) que você pode criar é limitado pelo pool nãopagado disponível. Cada solicitação de leitura ou gravação requer espaço no buffer para os dados de leitura ou gravação, além de espaço adicional para as estruturas de dados internas.

Os tamanhos de buffer de entrada e saída são consultivos. O tamanho real do buffer reservado para cada extremidade do pipe nomeado é o padrão do sistema, o mínimo ou o máximo do sistema ou o tamanho especificado arredondado para o próximo limite de alocação. O tamanho do buffer especificado deve ser pequeno o suficiente para que o processo não fique sem pool nãopagado, mas grande o suficiente para acomodar solicitações típicas.

Sempre que ocorre uma operação de gravação de pipe, o sistema primeiro tenta carregar a memória em relação à cota de gravação de pipe. Se a cota de gravação de pipe restante for suficiente para atender à solicitação, a operação de gravação será concluída imediatamente. Se a cota de gravação de pipe restante for muito pequena para atender à solicitação, o sistema tentará expandir os buffers para acomodar os dados usando o pool nãopagado reservado para o processo. A operação de gravação será bloqueada até que os dados sejam lidos do pipe para que a cota de buffer adicional possa ser liberada. Portanto, se o tamanho do buffer especificado for muito pequeno, o sistema aumentará o buffer conforme necessário, mas a desvantagem é que a operação será bloqueada. Se a operação for sobreposta, um thread do sistema será bloqueado; caso contrário, o thread do aplicativo será bloqueado.

Para liberar recursos usados por um pipe nomeado, o aplicativo sempre deve fechar identificadores quando eles não forem mais necessários, o que é feito chamando a função CloseHandle ou quando o processo associado aos identificadores de instância termina. Observe que uma instância de um pipe nomeado pode ter mais de um identificador associado a ele. Uma instância de um pipe nomeado sempre é excluída quando o último identificador para a instância do pipe nomeado é fechado.

Requisitos

Requisito Valor
parâmetro ntioapi.h
Biblioteca ntdll.lib