다음을 통해 공유

NtCreateNamedPipeFile 함수

  • 아티클

명명된 특정 파이프의 첫 번째 인스턴스 또는 기존 명명된 파이프의 다른 인스턴스의 서버 엔드 핸들을 만들고 엽니다. 함수는 파이프에 액세스하는 데 사용할 수 있는 핸들을 반환합니다.

구문

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
);

매개 변수

FileHandle [out]

호출에 성공하면 파일 핸들을 수신하는 변수에 대한 포인터입니다.

DesiredAccess [in]

호출자에게 필요한 파일 또는 디렉터리에 대한 액세스 유형을 지정하는 플래그의 비트 마스크입니다. 이 시스템 정의 DesiredAccess 플래그 집합은 파일 개체에 대해 다음과 같은 특정 액세스 권한을 결정합니다.

플래그 설명
Delete 파일을 삭제할 수 있습니다.
FILE_READ_DATA 데이터를 파일에서 읽을 수 있습니다.
FILE_READ_ATTRIBUTES 아래에 설명된 FileAttributes 플래그를 읽을 수 있습니다.
FILE_READ_EA 파일과 연결된 EA(확장 특성)를 읽을 수 있습니다.
READ_CONTROL 파일과 연결된 ACL(액세스 제어 목록) 및 소유권 정보를 읽을 수 있습니다.
FILE_WRITE_DATA 데이터를 파일에 쓸 수 있습니다.
FILE_WRITE_ATTRIBUTES FileAttributes 플래그를 작성할 수 있습니다.
FILE_WRITE_EA 파일과 연결된 EA를 작성할 수 있습니다.
FILE_APPEND_DATA 파일에 데이터를 추가할 수 있습니다.
WRITE_DAC 파일과 연결된 DACL(임의 액세스 제어 목록)을 작성할 수 있습니다.
WRITE_OWNER 파일과 연결된 소유권 정보를 작성할 수 있습니다.
SYNCHRONIZE 호출자는 반환된 FileHandle이 신호됨 상태로 설정될 때까지 대기하여 I/O 작업의 완료를 동기화할 수 있습니다. CreateOptions 또는 FILE_SYNCHRONOUS_IO_NONALERT 플래그가 설정된 경우 이 플래그를 FILE_SYNCHRONOUS_IO_ALERT 설정해야 합니다.
FILE_EXECUTE 시스템 페이징 I/O를 사용하여 파일에서 메모리로 데이터를 읽을 수 있습니다.

또는 디렉터리를 나타내지 않는 파일 개체의 경우 다음 제네릭 ACCESS_MASK 플래그 중 하나 이상을 지정할 수 있습니다. STANDARD_RIGHTS_XXX 플래그는 시스템 개체에 보안을 적용하는 데 사용되는 미리 정의된 시스템 값입니다. 이러한 제네릭 플래그를 이전 테이블의 추가 플래그와 결합할 수도 있습니다.

파일 값에 대한 원하는 액세스 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.

디렉터리( FILE_DIRECTORY_FILECreateOptions 플래그가 설정됨)의 경우 다음 ACCESS_MASK 플래그 중 하나 이상을 지정할 수 있으며, 앞에서 설명한 호환 플래그와 결합할 수도 있습니다.

디렉터리 값에 대한 원하는 액세스 Description
FILE_LIST_DIRECTORY 디렉터리의 파일을 나열할 수 있습니다.
FILE_TRAVERSE 디렉터리를 트래버스할 수 있습니다. 즉, 파일의 경로 이름에 속할 수 있습니다.

FILE_READ_DATA, FILE_WRITE_DATA, FILE_EXECUTE및 FILE_APPEND_DATADesiredAccess 플래그는 디렉터리 파일을 만들거나 여는 작업과 호환되지 않습니다.

ObjectAttributes [in]

OBJECT_ATTRIBUTES InitializeObjectAttributes 루틴에 의해 이미 초기화된 구조체에 대한 포인터입니다. 호출자가 시스템 프로세스 컨텍스트에서 실행 중인 경우 이 매개 변수는 일 수 있습니다 NULL. 그렇지 않으면 호출자는 InitializeObjectAttributes 호출에서 특성을 설정 OBJ_KERNEL_HANDLE 해야 합니다.

파일 개체에 대한 이 구조체의 멤버는 다음과 같습니다.

멤버 값
ULONG 길이 제공된 ObjectAttributes 데이터의 바이트 수입니다. 이 값은 적어도 sizeof(OBJECT_ATTRIBUTES)이어야 합니다.
PUNICODE_STRING ObjectName 만들거나 열 파일의 이름을 포함하는 버퍼링된 유니코드 문자열에 대한 포인터입니다. 이 값은 RootDirectory에서 지정한 디렉터리를 기준으로 하는 파일의 이름이 아니면 정규화된 파일 사양이어야 합니다. 예를 들어 "\Device\Floppy1\myfile.dat" 또는 "?? \B:\myfile.dat"는 플로피 디스크 드라이브 드라이버와 오버레이 파일 시스템이 이미 로드되어 있는 한 정규화된 파일 사양일 수 있습니다. (참고: "??"는 "\DosDevices"를 Win32 개체 네임스페이스의 이름으로 바꿉니다. "\DosDevices"는 계속 작동하지만 개체 관리자가 "??"를 더 빠르게 변환합니다.)
HANDLE RootDirectory NtCreateNamedPipeFile에 대한 이전 호출에서 가져온 디렉터리에 대한 선택적 핸들입니다. 이 값이 NULL인 경우 ObjectName 멤버는 대상 파일의 전체 경로를 포함하는 정규화된 파일 사양이어야 합니다. 이 값이 NULL이 아닌 경우 ObjectName 멤버는 이 디렉터리를 기준으로 파일 이름을 지정합니다.
PSECURITY_DESCRIPTOR SecurityDescriptor 파일에 적용할 선택적 보안 설명자입니다. 이러한 보안 설명자로 지정된 ACL은 파일을 만들 때만 적용됩니다. 파일을 만들 때 값이 NULL이면 파일에 배치된 ACL은 파일 시스템에 종속됩니다. 대부분의 파일 시스템은 호출자의 기본 ACL과 결합된 부모 디렉터리 파일에서 이러한 ACL의 일부를 전파합니다.
ULONG 특성 파일 개체 특성을 제어하는 플래그 집합입니다. 호출자가 시스템 프로세스 컨텍스트에서 실행 중인 경우 이 매개 변수는 0일 수 있습니다. 그렇지 않으면 호출자가 플래그를 OBJ_KERNEL_HANDLE 설정해야 합니다. 호출자는 필요에 따라 플래그를 OBJ_CASE_INSENSITIVE 설정할 수 있습니다. 이는 이름 조회 코드가 정확한 일치 검색을 수행하는 대신 ObjectName 의 대/소문자를 무시해야 함을 나타냅니다.

IoStatusBlock [out]

최종 완료 상태 및 요청된 작업에 대한 정보를 수신하는 형식 IO_STATUS_BLOCK 의 변수에 대한 포인터입니다. NtCreateNamedPipeFile에서 반환될 때 변수의 정보 멤버에는 다음 값 중 하나가 포함됩니다.

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

ShareAccess [in]

호출자가 원하는 파일에 대한 공유 액세스 유형을 0 또는 1 또는 다음 플래그의 조합으로 지정합니다. 단독 액세스를 요청하려면 이 매개 변수를 0으로 설정합니다. 위반 오류를 공유하지 않도록 하려면 다음 공유 액세스 플래그를 모두 지정합니다.

ShareAccess 플래그 Description
FILE_SHARE_READ 다른 스레드의 파일 만들기 호출에서 읽기 액세스를 위해 파일을 열 수 있습니다.
FILE_SHARE_WRITE 다른 스레드의 파일 만들기 호출을 통해 쓰기 액세스를 위해 파일을 열 수 있습니다.
FILE_SHARE_DELETE 다른 스레드의 파일 만들기 호출에 의해 액세스 삭제를 위해 파일을 열 수 있습니다.

디바이스 드라이버 및 중간 드라이버는 일반적으로 ShareAccess를 0으로 설정하므로 호출자에게 열려 있는 파일에 대한 단독 액세스 권한을 부여합니다.

CreateDisposition [in]

파일이 이미 있을 때 파일을 처리하는 방법을 결정하는 값입니다. CreateDisposition 은 다음 중 하나일 수 있습니다.

값 Description
FILE_SUPERSEDE 파일이 이미 있는 경우 지정된 파일로 바꿉니다. 존재하지 않는 경우 지정된 파일을 만듭니다.
FILE_CREATE 파일이 이미 있는 경우 요청에 실패하고 지정된 파일을 만들거나 열지 않습니다. 존재하지 않는 경우 지정된 파일을 만듭니다.
FILE_OPEN 파일이 이미 있는 경우 새 파일을 만드는 대신 엽니다. 존재하지 않는 경우 요청에 실패하고 새 파일을 만들지 않습니다.
FILE_OPEN_IF 파일이 이미 있는 경우 엽니다. 존재하지 않는 경우 지정된 파일을 만듭니다.
FILE_OVERWRITE 파일이 이미 있는 경우 파일을 열고 덮어씁니다. 존재하지 않는 경우 요청을 실패합니다.
FILE_OVERWRITE_IF 파일이 이미 있는 경우 파일을 열고 덮어씁니다. 존재하지 않는 경우 지정된 파일을 만듭니다.

CreateOptions [in]

파일을 만들거나 열 때 적용할 옵션을 다음 플래그의 호환 가능한 조합으로 지정합니다.

CreateOptions 플래그 Description
FILE_DIRECTORY_FILE(0x00000001) 만들거나 여는 파일은 디렉터리 파일입니다. 이 플래그를 사용하면 Disposition 매개 변수를 , FILE_OPEN또는 FILE_OPEN_IF중 FILE_CREATE하나로 설정해야 합니다. 이 플래그와 호환되는 CreateOptions 플래그는 FILE_SYNCHRONOUS_IO_ALERT, , FILE_SYNCHRONOUS_IO_NONALERT, FILE_WRITE_THROUGHFILE_OPEN_FOR_BACKUP_INTENT및 FILE_OPEN_BY_FILE_ID입니다.
FILE_WRITE_THROUGH(0x00000002) 요청된 쓰기 작업이 완료된 것으로 간주되기 전에 파일에 데이터를 쓰는 시스템 서비스, 파일 시스템 및 드라이버는 실제로 데이터를 파일로 전송해야 합니다.
FILE_SEQUENTIAL_ONLY(0x00000004) 파일에 대한 모든 액세스는 순차적으로 적용됩니다.
FILE_NO_INTERMEDIATE_BUFFERING(0x00000008) 파일은 드라이버의 내부 버퍼에서 캐시하거나 버퍼링할 수 없습니다. 이 플래그는 DesiredAccessFILE_APPEND_DATA 플래그와 호환되지 않습니다.
FILE_SYNCHRONOUS_IO_ALERT(0x00000010) 파일에 대한 모든 작업은 동기적으로 수행됩니다. 호출자를 대신하여 대기하는 모든 대기는 경고에서 조기 종료될 수 있습니다. 또한 이 플래그는 I/O 시스템에서 파일 위치 컨텍스트를 유지 관리하도록 합니다. 이 플래그가 설정된 경우 I/O 관리자가 파일 개체를 동기화 개체로 사용하도록 DesiredAccessSYNCHRONIZE 플래그도 설정해야 합니다.
FILE_SYNCHRONOUS_IO_NONALERT(0x00000020) 파일에 대한 모든 작업은 동기적으로 수행됩니다. 시스템에서 I/O 큐를 동기화하기 위한 대기 및 완료에는 경고가 적용되지 않습니다. 또한 이 플래그는 I/O 시스템에서 파일 위치 컨텍스트를 유지 관리하도록 합니다. 이 플래그가 설정된 경우 I/O 관리자가 파일 개체를 동기화 개체로 사용하도록 DesiredAccessSYNCHRONIZE 플래그도 설정해야 합니다.
FILE_NON_DIRECTORY_FILE(0x00000040) 열려 있는 파일이 디렉터리 파일이거나 이 호출이 실패하면 안 됩니다. 열려 있는 파일 개체는 데이터 파일을 나타낼 수 있습니다. 논리적, 가상 또는 물리적 디바이스 또는 볼륨입니다.
FILE_CREATE_TREE_CONNECTION(0x00000080) 네트워크를 통해 열려면 이 파일에 대한 트리 연결을 만듭니다.
FILE_COMPLETE_IF_OPLOCKED(0x00000100) 호출자의 스레드를 차단하는 대신 대상 파일이 잠겨 있는 경우 대체 성공 코드로 이 작업을 즉시 완료합니다. 파일이 잠겨 있으면 다른 호출자가 이미 네트워크를 통해 파일에 액세스할 수 있습니다.
FILE_NO_EA_KNOWLEDGE(0x00000200) 열려 있는 기존 파일의 확장 특성이 호출자가 파일을 제대로 해석하기 위해 확장 특성을 이해해야 함을 나타내는 경우 호출자가 확장 특성을 처리하는 방법을 이해하지 못하기 때문에 이 요청에 실패합니다.
FILE_OPEN_REMOTE_INSTANCE(0x00000400) 시스템 사용을 위해 예약됨; 를 사용하지 마세요.
FILE_RANDOM_ACCESS(0x00000800) 파일에 대한 액세스는 임의일 수 있으므로 파일 시스템 또는 운영 체제에서 파일에서 순차적 미리 읽기 작업을 수행해서는 안 됩니다.
FILE_DELETE_ON_CLOSE(0x00001000) 마지막 핸들이 FltClose에 전달되면 파일을 삭제합니다.
FILE_OPEN_BY_FILE_ID(0x00002000) ID로 파일을 열고 있습니다. 파일 이름에는 디바이스 이름과 파일을 여는 데 사용할 64비트 ID가 포함됩니다.
FILE_OPEN_FOR_BACKUP_INTENT(0x000004000) 백업 의도를 위해 파일이 열리고 있습니다. 따라서 시스템은 파일의 보안 설명자에 대해 DesiredAccess 입력을 확인하기 전에 특정 액세스 권한을 확인하고 호출자에게 파일에 대한 적절한 액세스 권한을 부여해야 합니다.
FILE_NO_COMPRESSION(0x00008000) 부모 디렉터리에서 의 FILE_ATTRIBUTE_COMPRESSED 상속을 표시하지 않습니다. 이렇게 하면 압축된 것으로 표시된 디렉터리에서 압축되지 않은 파일을 만들 수 있습니다.
FILE_OPEN_REQUIRING_OPLOCK(0x00010000) 파일이 열리고 파일에 대한 기회 잠금(oplock)이 단일 원자성 작업으로 요청됩니다. 파일 시스템은 만들기 작업을 수행하기 전에 oplock을 확인하고 만들기 작업이 기존 oplock을 중단하는 경우 의 STATUS_CANNOT_BREAK_OPLOCK 반환 코드와 함께 만들기 작업이 실패합니다. 이 플래그는 Windows 7, Windows Server 2008 R2 이상 Windows 운영 체제에서 사용할 수 있습니다.
FILE_DISALLOW_EXCLUSIVE(0x00020000) 기존 파일을 열 때 가 지정되지 않고 파일 시스템 액세스 검사에서 호출자에게 파일에 대한 쓰기 권한을 부여하지 않는 경우 FILE_SHARE_READ 를 사용하여 이 열기 STATUS_ACCESS_DENIED에 실패합니다. 이는 Windows 7 이전의 기본 동작이었습니다.
FILE_SESSION_AWARE(0x00040000) 파일 또는 디바이스가 세션 인식으로 열리고 있습니다. 이 플래그를 지정하지 않으면 세션 0에서 실행되는 프로세스에서 세션별 디바이스(예: RemoteFX USB 리디렉션을 사용하는 디바이스)를 열 수 없습니다. 이 플래그는 세션 0에 없는 호출자에게는 적용되지 않습니다. 이 플래그는 Windows 서버 버전에서만 지원됩니다. 이 플래그는 Windows Server 2012 전에 지원되지 않습니다.
FILE_RESERVE_OPFILTER(0x00100000) 이 플래그를 사용하면 애플리케이션이 필터 기회 잠금(oplock)을 요청하여 다른 애플리케이션이 공유 위반을 받지 못하도록 할 수 있습니다. 열려 있는 핸들이 이미 있는 경우 만들기 요청은 와 함께 STATUS_OPLOCK_NOT_GRANTED실패합니다.
FILE_OPEN_REPARSE_POINT(0x00200000) 재분석 지점이 있는 파일을 열고 파일에 대한 일반 재분석 지점 처리를 무시합니다. 자세한 내용은 아래 설명 부분을 참조하십시오.
FILE_OPEN_NO_RECALL(0x00400000) 오프라인 스토리지 또는 가상화를 수행하는 필터에 이 열기의 결과로 파일의 내용을 회수하지 않도록 지시합니다.
FILE_OPEN_FOR_FREE_SPACE_QUERY(0x00800000) 이 플래그는 호출 스레드와 연결된 사용자를 캡처하도록 파일 시스템에 지시합니다. 반환된 핸들을 사용하여 FltQueryVolumeInformation 또는 ZwQueryVolumeInformationFile 에 대한 후속 호출은 호출자가 사용할 수 있는 여유 공간을 계산하기 위해 당시 호출 사용자가 아닌 캡처된 사용자를 가정합니다. 이는 FsInformationClass 값 FileFsSizeInformation, , FileFsFullSizeInformation및 FileFsFullSizeInformationEx에 적용됩니다.

NamedPipeType [in]

만들 명명된 파이프의 형식(바이트 형식 또는 메시지 형식)입니다.

ReadMode [in]

파이프를 읽을 모드(바이트 형식 또는 메시지 유형)입니다.

CompletionMode [in]

작업을 완료하는 방법을 지정합니다.

MaximumInstances [in]

명명된 파이프의 최대 동시 인스턴스 수입니다.

InboundQuota [in]

명명된 파이프의 인바운드 쪽에 쓰기를 위해 예약된 풀 할당량을 지정합니다.

아웃바운드쿼타 [in]

명명된 파이프의 인바운드 쪽에 쓰기를 위해 예약된 풀 할당량을 지정합니다.

DefaultTimeout [in, optional]

명명된 파이프의 인스턴스를 대기할 때 시간 제한 값을 지정하지 않은 경우 사용되는 시간 제한 값에 대한 선택적 포인터입니다.

반환

함수 값은 만들기/열기 작업의 최종 상태입니다.

설명

명명된 파이프의 인스턴스를 만들려면 사용자가 명명된 파이프 개체에 대한 FILE_CREATE_PIPE_INSTANCE 액세스 권한이 있어야 합니다. 명명된 새 파이프를 만드는 경우 보안 특성 매개 변수의 ACL(액세스 제어 목록)은 명명된 파이프에 대한 임의 액세스 제어를 정의합니다.

명명된 파이프의 모든 인스턴스는 동일한 파이프 유형(바이트 형식 또는 메시지 형식), 파이프 액세스(이중, 인바운드 또는 아웃바운드), 인스턴스 수 및 제한 시간 값을 지정해야 합니다. 다른 값을 사용하는 경우 이 함수는 실패하고 GetLastError 는 ERROR_ACCESS_DENIED 반환합니다.

클라이언트 프로세스는 CreateFile 또는 CallNamedPipe 함수를 사용하여 명명된 파이프에 연결합니다. 서버 쪽이 메시지 모드인 경우에도 명명된 파이프의 클라이언트 쪽이 바이트 모드로 시작됩니다. 데이터 수신 문제를 방지하려면 클라이언트 쪽도 메시지 모드로 설정합니다. 파이프 모드를 변경하려면 파이프 클라이언트가 GENERIC_READFILE_WRITE_ATTRIBUTES 액세스 권한이 있는 읽기 전용 파이프를 열어야 합니다.

파이프 서버는 파이프 클라이언트가 시작될 때까지 읽기 차단 작업을 수행해서는 안 됩니다. 그렇지 않으면 경합 상태가 발생할 수 있습니다. 이는 일반적으로 C 런타임과 같은 초기화 코드가 상속된 핸들을 잠그고 검사해야 하는 경우에 발생합니다.

명명된 파이프를 만들 때마다 시스템은 커널에서 사용하는 실제 메모리인 비페이지 풀을 사용하여 인바운드 및/또는 아웃바운드 버퍼를 만듭니다. 만들 수 있는 파이프 인스턴스(스레드 및 프로세스와 같은 개체)의 수는 사용 가능한 비페이지 풀에 의해 제한됩니다. 각 읽기 또는 쓰기 요청에는 읽기 또는 쓰기 데이터에 대한 버퍼의 공간과 내부 데이터 구조에 대한 추가 공간이 필요합니다.

입력 및 출력 버퍼 크기는 권고입니다. 명명된 파이프의 각 끝에 예약된 실제 버퍼 크기는 시스템 기본값, 시스템 최소값 또는 최대값 또는 다음 할당 경계로 반올림된 지정된 크기입니다. 지정된 버퍼 크기는 프로세스에 페이지가 없는 풀이 부족하지 않고 일반적인 요청을 수용할 수 있을 만큼 충분히 커야 합니다.

파이프 쓰기 작업이 발생할 때마다 시스템은 먼저 파이프 쓰기 할당량에 대해 메모리를 충전하려고 시도합니다. 나머지 파이프 쓰기 할당량이 요청을 이행하기에 충분하면 쓰기 작업이 즉시 완료됩니다. 나머지 파이프 쓰기 할당량이 너무 작아서 요청을 처리할 수 없는 경우 시스템은 프로세스에 예약된 비페이지 풀을 사용하여 데이터를 수용하도록 버퍼를 확장하려고 합니다. 추가 버퍼 할당량을 해제할 수 있도록 파이프에서 데이터를 읽을 때까지 쓰기 작업이 차단됩니다. 따라서 지정된 버퍼 크기가 너무 작으면 시스템은 필요에 따라 버퍼를 증가하지만 단점은 작업이 차단된다는 것입니다. 작업이 겹치면 시스템 스레드가 차단됩니다. 그렇지 않으면 애플리케이션 스레드가 차단됩니다.

명명된 파이프에서 사용하는 리소스를 해제하려면 애플리케이션이 더 이상 필요하지 않을 때 항상 핸들을 닫아야 합니다. 이는 CloseHandle 함수를 호출하거나 인스턴스 핸들과 연결된 프로세스가 종료될 때 수행됩니다. 명명된 파이프의 인스턴스에는 둘 이상의 핸들이 연결되어 있을 수 있습니다. 명명된 파이프의 인스턴스는 명명된 파이프의 인스턴스에 대한 마지막 핸들이 닫혀 있을 때 항상 삭제됩니다.

요구 사항

요구 사항 값
헤더 ntioapi.h
라이브러리 ntdll.lib