FltCreateNamedPipeFile 함수(fltkernel.h)
미니필터 드라이버는 FltCreateNamedPipeFile 을 호출하여 새 파이프를 만들거나 기존 파이프를 엽니다.
구문
NTSTATUS FLTAPI FltCreateNamedPipeFile(
[in] PFLT_FILTER Filter,
[in, optional] PFLT_INSTANCE Instance,
[out] PHANDLE FileHandle,
[out, optional] PFILE_OBJECT *FileObject,
[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,
ULONG InboundQuota,
ULONG OutboundQuota,
[in, optional] PLARGE_INTEGER DefaultTimeout,
[in, optional] PIO_DRIVER_CREATE_CONTEXT DriverContext
);
매개 변수
[in] Filter
호출자에 대한 불투명 필터 포인터입니다.
[in, optional] Instance
만들기 요청을 보낼 미니필터 드라이버 instance 대한 불투명 instance 포인터입니다. instance 명명된 파이프 파일 시스템의 볼륨에 연결해야 합니다. 이 매개 변수는 선택 사항이며 NULL일 수 있습니다. 이 매개 변수가 NULL인 경우 요청은 볼륨에 대한 파일 시스템 드라이버 스택의 맨 위에 있는 디바이스 개체로 전송됩니다. NULL이 아닌 경우 요청은 지정된 instance 아래에 연결된 미니필터 드라이버 인스턴스로만 전송됩니다.
[out] FileHandle
FltCreateNamedPipeFile에 대한 호출이 성공한 경우 파일 핸들을 수신하는 호출자 할당 변수에 대한 포인터입니다.
[out, optional] FileObject
FltCreateNamedPipeFile 호출에 성공한 경우 파일 개체 포인터를 수신하는 호출자 할당 변수에 대한 포인터입니다. 이 매개 변수는 선택 사항이며 NULL일 수 있습니다.
[in] DesiredAccess
호출자가 파일 또는 디렉터리에 필요한 액세스 유형을 지정하는 플래그의 비트 마스크입니다. 시스템 정의 DesiredAccess 플래그 집합은 파일 개체에 대해 다음과 같은 특정 액세스 권한을 결정합니다.
| DesiredAccess 플래그 | 의미 |
|---|---|
| FILE_READ_DATA | 명명된 파이프에서 데이터를 읽을 수 있습니다. |
| FILE_READ_ATTRIBUTES | FileAttributes 플래그를 읽을 수 있습니다. 자세한 내용은 FltCreateFileEx2의 FileAttributes 매개 변수에서 유효한 플래그 값 테이블을 참조하세요. |
| READ_CONTROL | 명명된 파이프와 연결된 ACL(액세스 제어 목록) 및 소유권 정보를 읽을 수 있습니다. |
| FILE_WRITE_DATA | 명명된 파이프에 데이터를 쓸 수 있습니다. |
| FILE_WRITE_ATTRIBUTES | FileAttributes 플래그를 작성할 수 있습니다. |
| FILE_APPEND_DATA | 파일에 데이터를 추가할 수 있습니다. |
| WRITE_DAC | 명명된 파이프와 연결된 DACL(임의 액세스 제어 목록)을 작성할 수 있습니다. |
| WRITE_OWNER | 명명된 파이프와 연결된 소유권 정보를 작성할 수 있습니다. |
| ACCESS_SYSTEM_SECURITY | 호출자는 명명된 파이프의 SACL에 대한 쓰기 권한을 갖습니다. |
| SYNCHRONIZE | 호출자는 반환된 FileHandle 이 신호됨 상태로 설정될 때까지 대기하여 I/O 작업의 완료를 동기화할 수 있습니다. CreateOptions FILE_SYNCHRONOUS_IO_ALERT 또는 FILE_SYNCHRONOUS_IO_NONALERT 플래그가 설정된 경우 이 플래그를 설정해야 합니다. |
또는 디렉터리를 나타내지 않는 파일 개체의 경우 다음 제네릭 ACCESS_MASK 플래그 중 하나 이상을 지정할 수 있습니다. (STANDARD_RIGHTS_XXX 플래그는 시스템 개체에 보안을 적용하는 데 사용되는 미리 정의된 시스템 값입니다.) 이러한 제네릭 플래그를 이전 테이블의 추가 플래그와 결합할 수도 있습니다.
| DesiredAccess에서 파일 값으로 | DesiredAccess 플래그에 매핑 |
|---|---|
| GENERIC_READ | STANDARD_RIGHTS_READ, FILE_READ_DATA 및 SYNCHRONIZE. |
| GENERIC_WRITE | STANDARD_RIGHTS_WRITE, FILE_WRITE_DATA, FILE_APPEND_DATA 및 SYNCHRONIZE. |
[in] ObjectAttributes
InitializeObjectAttributes를 사용하여 이미 초기화된 불투명 OBJECT_ATTRIBUTES 구조체에 대한 포인터입니다. 호출자가 시스템 프로세스 컨텍스트에서 실행 중인 경우 이 매개 변수는 NULL일 수 있습니다. 그렇지 않으면 호출자는 InitializeObjectAttributes 호출에서 OBJ_KERNEL_HANDLE 특성을 설정해야 합니다. 파일 개체에 대한 이 구조체의 멤버는 다음 표에 나와 있습니다.
| 멤버 | 값 |
|---|---|
| ULONG 길이 | ObjectAttributes가 가리키는 구조체에 포함된 데이터 바이트 수입니다. 이 값은 sizeof(OBJECT_ATTRIBUTES) 이상이어야 합니다. |
| PUNICODE_STRING ObjectName | 만들거나 열 파이프의 이름을 포함하는 UNICODE_STRING 구조체에 대한 포인터입니다. RootDirectory에서 지정한 디렉터리를 기준으로 하는 파일의 이름이 아니면 이 이름은 정규화된 파일 사양이거나 디바이스 개체의 이름이어야 합니다. 예: "\Device\NamedPipe\mypipe" 또는 "\?? \pipe\mypipe"는 모두 유효한 파일 사양일 수 있습니다. (참고: "\??"는 "\DosDevices"를 Win32 개체 네임스페이스의 이름으로 바꿉니다. "\DosDevices"는 계속 작동하지만 개체 관리자가 "\??"를 더 빠르게 변환합니다.) |
| HANDLE RootDirectory | FltCreateFileEx2에 대한 이전 호출에서 가져온 디렉터리에 대한 선택적 핸들입니다. 이 값이 NULL인 경우 ObjectName멤버는 대상 파이프의 전체 경로를 포함하는 정규화된 파일 사양이어야 합니다. 이 값이 NULL이 아닌 경우 ObjectName 멤버는 이 디렉터리를 기준으로 하는 파이프 이름을 지정합니다. |
| PSECURITY_DESCRIPTOR SecurityDescriptor | 파이프에 적용할 선택적 보안 설명자(SECURITY_DESCRIPTOR)입니다. 이러한 보안 설명자로 지정된 ACL은 생성될 때만 파이프에 적용됩니다. 파이프를 만들 때 값이 NULL이면 파이프에 배치된 ACL은 명명된 파이프 파일 시스템에 따라 달라지고 액세스 권한이 있는 클라이언트가 instance 만들 수 있습니다. |
| ULONG 특성 | 파일 개체 특성을 제어하는 플래그 집합입니다. 호출자가 시스템 프로세스 컨텍스트에서 실행 중인 경우 이 매개 변수는 0일 수 있습니다. 그렇지 않으면 호출자가 OBJ_KERNEL_HANDLE 플래그를 설정해야 합니다. 호출자는 필요에 따라 OBJ_CASE_INSENSITIVE 플래그를 설정할 수 있습니다. 이는 이름 조회 코드가 정확한 일치 검색을 수행하는 대신 ObjectName 의 대/소문자를 무시해야 함을 나타냅니다. |
[out] IoStatusBlock
최종 완료 상태 수신하는 IO_STATUS_BLOCK 구조체에 대한 포인터 및 요청된 작업에 대한 정보입니다. FltCreateNamedPipeFile에서 반환될 때 변수의 정보 멤버에는 다음 값 중 하나가 포함됩니다.
FILE_CREATED
FILE_OPENED
[in] ShareAccess
호출자가 다음 플래그의 하나 또는 조합으로 필요로 하는 파일에 대한 공유 액세스 유형입니다. 공유 위반 오류를 방지할 가능성이 가장 높은 경우 다음 공유 액세스 플래그를 모두 지정합니다.
| ShareAccess 플래그 | 의미 |
|---|---|
| FILE_SHARE_READ | FltCreateNamedPipeFile에 대한 다른 스레드 호출을 통해 읽기 액세스를 위해 파일을 열 수 있습니다. |
| FILE_SHARE_WRITE | FltCreateNamedPipeFile에 대한 다른 스레드 호출을 통해 쓰기 액세스를 위해 파일을 열 수 있습니다. |
[in] CreateDisposition
파일이 이미 있는지 여부에 따라 수행할 작업을 결정하는 값입니다. 값은 다음 표에 설명된 값일 수 있습니다.
| CreateDisposition 값 | 의미 |
|---|---|
| FILE_CREATE | 파일이 이미 있는 경우 요청에 실패하고 지정된 파일을 만들거나 열지 않습니다. 그렇지 않으면 파일을 만듭니다. |
| FILE_OPEN | 파일이 이미 있는 경우 새 파일을 만드는 대신 엽니다. 그렇지 않은 경우 요청을 실패하고 새 파일을 만들지 않습니다. |
| FILE_OPEN_IF | 파일이 이미 있는 경우 파일을 엽니다. 그렇지 않으면 파일을 만듭니다. |
[in] CreateOptions
다음 플래그의 호환 조합으로 파이프를 만들거나 열 때 적용할 옵션입니다.
| CreateOptions 플래그 | 의미 |
|---|---|
| FILE_WRITE_THROUGH | 파이프에 데이터를 쓰는 시스템 서비스, 파이프 시스템 및 드라이버는 요청된 쓰기 작업이 완료된 것으로 간주되기 전에 실제로 데이터를 파이프로 전송해야 합니다. CreateOptions 플래그 FILE_NO_INTERMEDIATE_BUFFERING 설정되면 이 플래그가 자동으로 설정됩니다. |
| FILE_SYNCHRONOUS_IO_ALERT | 파이프의 모든 작업은 동기적으로 수행됩니다. 호출자를 대신하여 대기하는 모든 대기는 경고에서 조기 종료될 수 있습니다. 또한 이 플래그를 사용하면 I/O 시스템이 파이프 위치 컨텍스트를 유지 관리합니다. 이 플래그가 설정되면 I/O 관리자가 파일 개체를 동기화 개체로 사용하도록 DesiredAccess SYNCHRONIZE 플래그도 설정해야 합니다. |
| FILE_SYNCHRONOUS_IO_NONALERT | 파이프의 모든 작업은 동기적으로 수행됩니다. 시스템에서 I/O 큐를 동기화하기 위한 대기 및 완료에는 경고가 적용되지 않습니다. 또한 이 플래그를 사용하면 I/O 시스템이 파일 위치 컨텍스트를 유지 관리합니다. 이 플래그가 설정되면 I/O 관리자가 파일 개체를 동기화 개체로 사용하도록 DesiredAccess SYNCHRONIZE 플래그도 설정해야 합니다. |
[in] NamedPipeType
만들 명명된 파이프의 형식입니다. 다음 값 중 하나일 수 있습니다.
| 값 | 의미 |
|---|---|
|
데이터는 바이트 스트림으로 파이프에 기록됩니다. 이 형식을 사용하려면 ReadMode 를 FILE_PIPE_MESSAGE_MODE 않아야 합니다. |
|
데이터는 메시지로 파이프에 기록됩니다. |
[in] ReadMode
파이프에서 읽을 모드입니다.
| 값 | 의미 |
|---|---|
|
파이프 데이터는 바이트 스트림으로 읽습니다. |
|
파이프 데이터는 메시지로 읽습니다. 이 모드를 사용하려면 NamedPipeType 을 FILE_PIPE_MESSAGE_TYPE 합니다. |
[in] CompletionMode
파이프 읽기 및 쓰기에 대한 완료 모드입니다.
| 값 | 의미 |
|---|---|
|
파이프 읽기 및 쓰기 요청은 큐에 대기되며 완료될 때까지 차단할 수 있습니다. |
|
파이프 읽기 및 쓰기 요청이 즉시 완료됩니다. |
[in] MaximumInstances
이 명명된 파이프에 허용되는 최대 인스턴스 수입니다.
InboundQuota
입력 버퍼에 대해 예약할 바이트 수입니다.
OutboundQuota
출력 버퍼에 대해 예약할 바이트 수입니다.
[in, optional] DefaultTimeout
기본 시간 제한(100나노초 증분)입니다. 이 값은 음수 정수로 표현됩니다. 예를 들어 250밀리초는 –10 * 1000 * 250으로 지정됩니다.
[in, optional] DriverContext
IoInitializeDriverCreateContext에 의해 이미 초기화된 IO_DRIVER_CREATE_CONTEXT 구조체에 대한 선택적 포인터입니다.
반환 값
FltCreateNamedPipeFile은 STATUS_SUCCESS 또는 다음 중 하나와 같은 적절한 NTSTATUS 값을 반환합니다.
| 반환 코드 | 설명 |
|---|---|
|
필터 또는 인스턴스 매개 변수에 지정된 필터 또는 instance 삭제되고 있습니다. 열린 요청이 볼륨 탑재 지점을 넘고 Instance 매개 변수가 NULL이 아닌 경우 이 상태 코드를 받을 수 있습니다. 오류 코드입니다. |
|
ObjectAttributes 매개 변수에 RootDirectory 멤버가 없지만 OBJECT_ATTRIBUTES 구조체의 ObjectName 멤버는 빈 문자열이거나 OBJECT_NAME_PATH_SEPARATOR 문자를 포함하지 않았습니다. 이 오류 코드는 개체 경로에 대한 잘못된 구문을 나타냅니다. |
설명
FltCreateNamedPipeFile 함수를 사용하면 미니필터 드라이버가 파이프 인스턴스를 만들거나 열 수 있습니다. 이는 가상 파이프를 만들거나 I/O 멀티플렉싱을 위한 파이프 공용 구조체를 만드는 데 유용합니다.
instance 매개 변수는 NULL이거나 이전에 명명된 파이프 볼륨에 연결하여 설정되었습니다. 볼륨 포인터는 "\Device\NamedPipe"를 FltGetVolumeFromName에 볼륨 이름으로 전달하여 가져옵니다.
추가 ECP(create 매개 변수)를 만들기 작업의 일부로 지정하려면 FltAllocateExtraCreateParameterList 루틴을 사용하여 IO_DRIVER_CREATE_CONTEXT 구조체의 ExtraCreateParameter 멤버를 초기화합니다. ECP를 사용하는 경우 관련 지원 루틴을 사용하여 할당, 초기화 및 해제해야 합니다. FltCreateNamedPipeFile 호출에서 돌아오면 ECP 목록은 변경되지 않으며 다른 만들기 작업을 위해 FltCreateNamedPipeFile의 추가 호출에 전달될 수 있습니다. ECP 목록 구조는 자동으로 할당 취소되지 않습니다. FltCreateNamedPipeFile의 호출자는 FltFreeExtraCreateParameterList 루틴을 호출하여 이 구조체의 할당을 취소해야 합니다.
Instance가 NULL이 아닌 경우 FltCreateNamedPipeFile의 만들기 요청은 지정된 미니필터 드라이버 instance 아래에 연결된 인스턴스와 명명된 파이프 파일 시스템으로만 전송됩니다. 지정된 instance 위에 연결된 인스턴스는 만들기 요청을 받지 않습니다. instance 지정하지 않으면 요청이 스택의 맨 위로 이동하고 모든 인스턴스와 명명된 파이프 파일 시스템에서 수신됩니다.
요구 사항
| 요구 사항 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Windows 8 사용할 수 있습니다. |
| 대상 플랫폼 | 유니버설 |
| 헤더 | fltkernel.h(FltKernel.h 포함) |
| 라이브러리 | Fltmgr.lib |
| IRQL | PASSIVE_LEVEL |
추가 정보
FltAllocateExtraCreateParameterList
피드백
출시 예정: 2024년 내내 콘텐츠에 대한 피드백 메커니즘으로 GitHub 문제를 단계적으로 폐지하고 이를 새로운 피드백 시스템으로 바꿀 예정입니다. 자세한 내용은 다음을 참조하세요. https://aka.ms/ContentUserFeedback
다음에 대한 사용자 의견 제출 및 보기