CREATEFILE2_EXTENDED_PARAMETERS 구조체(fileapi.h)
CreateFile2에 대한 선택적 확장 매개 변수를 포함합니다.
구문
typedef struct _CREATEFILE2_EXTENDED_PARAMETERS {
DWORD dwSize;
DWORD dwFileAttributes;
DWORD dwFileFlags;
DWORD dwSecurityQosFlags;
LPSECURITY_ATTRIBUTES lpSecurityAttributes;
HANDLE hTemplateFile;
} CREATEFILE2_EXTENDED_PARAMETERS, *PCREATEFILE2_EXTENDED_PARAMETERS, *LPCREATEFILE2_EXTENDED_PARAMETERS;
멤버
dwSize
이 구조 sizeof(CREATEFILE2_EXTENDED_PARAMETERS)체의 크기를 포함합니다.
dwFileAttributes
파일 또는 디바이스 특성 및 플래그이며 , FILE_ATTRIBUTE_NORMAL 파일에 대한 가장 일반적인 기본값입니다.
이 매개 변수는 사용 가능한 파일 특성(FILE_ATTRIBUTE_*)의 조합을 포함할 수 있습니다. 다른 모든 파일 특성은 FILE_ATTRIBUTE_NORMAL 재정의합니다.
참고
CreateFile2에서 기존 파일을 열면 일반적으로 파일 플래그를 기존 파일의 파일 특성과 결합하고 dwFlagsAndAttributes의 일부로 제공된 모든 파일 특성을 무시합니다. 특수 사례는 파일 만들기 및 열기에 자세히 설명되어 있습니다.
다음 파일 특성 및 플래그 중 일부는 파일에만 적용할 수 있으며 CreateFile2 에서 열 수 있는 다른 모든 유형의 디바이스는 적용할 수 없습니다. 자세한 내용은 참조 페이지의 설명 섹션 CreateFile2 및 파일 만들기 및 열기를 참조하세요.
파일 특성에 대한 고급 액세스는 SetFileAttributes를 참조하세요. 해당 값과 설명이 포함된 모든 파일 특성의 전체 목록은 파일 특성 상수를 참조하세요.
| attribute | 의미 |
|---|---|
|
파일을 보관해야 합니다. 애플리케이션은 이 특성을 사용하여 파일을 백업 또는 제거로 표시합니다. |
|
파일이나 디렉터리가 암호화되어 있습니다. 파일의 경우 파일의 모든 데이터가 암호화됨을 의미합니다. 디렉터리의 경우 암호화가 새로 만든 파일 및 하위 디렉터리의 기본값임을 의미합니다. 자세한 내용은 파일 암호화를 참조하세요.
FILE_ATTRIBUTE_SYSTEM 지정한 경우에도 이 플래그는 적용되지 않습니다. 이 플래그는 Windows의 Home, Home Premium, Starter 또는 ARM 버전에서 지원되지 않습니다. 이 플래그는 Windows 스토어 앱에서 호출할 때 지원되지 않습니다. |
|
파일이 숨겨집니다. 일반 디렉터리 목록에 포함하지 마세요. |
|
무결성으로 구성된 파일 또는 디렉터리입니다. 파일의 경우 파일의 모든 데이터 스트림은 무결성을 갖습니다. 디렉터리의 경우 호출자가 달리 지정하지 않는 한 새로 만든 파일 및 하위 디렉터리의 기본값은 무결성입니다.
이 플래그는 ReFS 파일 시스템에서만 지원됩니다. |
|
파일에 다른 특성이 설정되어 있지 않습니다. 이 특성은 단독으로 사용될 때만 유효합니다. |
|
파일의 데이터를 즉시 사용할 수 없습니다. 이 특성은 파일 데이터가 오프라인 스토리지로 물리적으로 이동되었음을 나타냅니다. 이 특성은 계층적 스토리지 관리 소프트웨어인 Remote Storage에서 사용됩니다. 애플리케이션이 이 특성을 임의로 변경해서는 안 됩니다. |
|
파일은 읽기 전용입니다. 애플리케이션은 파일을 읽을 수 있지만 파일을 쓰거나 삭제할 수는 없습니다. |
|
파일의 일부이거나 운영 체제에서만 사용됩니다. |
|
파일이 임시 스토리지에 사용되고 있습니다.
자세한 내용은 이 항목의 캐싱 동작 섹션을 참조하세요. |
dwFileFlags
이 매개 변수는 파일 또는 디바이스 캐싱 동작, 액세스 모드 및 기타 특수 용도 플래그를 제어하기 위한 플래그 조합(FILE_FLAG_*)을 포함할 수 있습니다.
| 플래그 | 의미 |
|---|---|
|
백업 또는 복원 작업을 위해 파일을 열거나 만듭니다. 시스템은 프로세스에 SE_BACKUP_NAME 및SE_RESTORE_NAME 권한이 있는 경우 호출 프로세스가 파일 보안 검사를 재정의하도록 합니다. 자세한 내용은 토큰의 권한 변경을 참조하세요.
디렉터리에 대한 핸들을 가져오려면 이 플래그를 설정해야 합니다. 디렉터리 핸들은 파일 핸들 대신 일부 함수에 전달할 수 있습니다. 자세한 내용은 주의 섹션을 참조하세요. |
|
이 파일은 지정된 핸들과 다른 열린 핸들이나 중복 핸들을 포함하여 모든 핸들이 닫힌 직후 삭제됩니다.
파일에 대한 기존 열린 핸들이 있는 경우 FILE_SHARE_DELETE 공유 모드로 열려 있지 않으면 호출이 실패합니다. FILE_SHARE_DELETE 공유 모드가 지정되지 않은 경우에는 파일에 대한 후속 열기 요청이 실패합니다. |
|
디바이스 맵은 시스템의 DOS 디바이스 이름과 디바이스 간의 매핑이며 DOS 이름을 확인할 때 사용됩니다. 시스템의 각 사용자에 대해 별도의 디바이스 맵이 있으며 사용자는 자신의 디바이스 맵을 관리할 수 있습니다. 일반적으로 가장하는 동안 가장된 사용자의 디바이스 맵이 사용됩니다. 그러나 이 플래그가 설정되면 프로세스 사용자의 디바이스 맵이 대신 사용됩니다. |
|
파일 또는 디바이스가 데이터 읽기 및 쓰기에 대한 시스템 캐싱 없이 열리고 있습니다. 이 플래그는 하드 디스크 캐싱 또는 메모리 매핑된 파일에 영향을 주지 않습니다.
FILE_FLAG_NO_BUFFERING 플래그를 사용하여 CreateFile2로 열린 파일을 성공적으로 사용하기 위한 엄격한 요구 사항이 있습니다. 자세한 내용은 파일 버퍼링을 참조하세요. |
|
파일 데이터가 요청되지만 원격 스토리지에 계속 위치해야 합니다. 로컬 스토리지로 다시 전송해서는 안 됩니다. 이 플래그는 원격 스토리지 시스템에서 사용하기 위한 것입니다. |
|
일반적인 재문 분석 지점 처리는 발생하지 않습니다. CreateFile2 는 재분석 지점을 열려고 시도합니다. 파일을 열면 재분석 지점을 제어하는 필터가 작동하는지 여부에 관계없이 파일 핸들이 반환됩니다.
이 플래그는 CREATE_ALWAYS 플래그와 함께 사용할 수 없습니다. 파일이 재분석 지점이 아닌 경우 이 플래그는 무시됩니다. 자세한 내용은 주의 섹션을 참조하세요. |
|
파일이 열리고 파일의 기회 잠금(oplock)이 단일 원자성 작업으로 요청됩니다. 파일 시스템은 만들기 작업을 수행하기 전에 oplock을 확인하고, 결과가 기존 oplock을 중단하는 경우 ERROR_CANNOT_BREAK_OPLOCK 마지막 오류 코드로 만들기에 실패합니다.
이 플래그를 사용하고 CreateFile2 함수를 호출하면 파일 핸들에서 수행해야 하는 첫 번째 작업은 DeviceIOControl 함수를 호출한 다음 FSCTL_REQUEST_OPLOCK 또는 다른 기회 잠금 작업 중 하나를 전달하여 oplock을 요청하는 것입니다. oplock을 요청하기 전에 파일 핸들을 사용하여 다른 파일 시스템 작업을 수행하는 경우 교착 상태가 발생할 수 있습니다. 참고 먼저 oplock을 요청하지 않고 파일 핸들에서 CloseHandle 함수를 안전하게 호출할 수 있습니다.
|
|
파일 또는 디바이스가 비동기 I/O용으로 열리거나 생성되고 있습니다.
이 핸들에서 후속 I/O 작업이 완료되면 OVERLAPPED 구조에 지정된 이벤트가 신호 상태로 설정됩니다. 이 플래그를 지정하면 파일을 동시 읽기 및 쓰기 작업에 사용할 수 있습니다. 이 플래그를 지정하지 않으면 읽기 및 쓰기 함수에 대한 호출이 OVERLAPPED 구조를 지정하더라도 I/O 작업이 직렬화됩니다. 이 플래그로 만든 파일 핸들을 사용할 때 고려 사항에 대한 자세한 내용은 이 항목의 동기 및 비동기 I/O 핸들 섹션을 참조하세요. |
|
액세스는 POSIX 규칙에 따라 발생합니다. 여기에는 이름 지정을 지원하는 파일 시스템에 대해서만 이름이 다른 여러 파일을 허용하는 것이 포함됩니다. 이 플래그로 만든 파일은 MS-DOS 또는 16비트 Windows용으로 작성된 애플리케이션에서 액세스할 수 없으므로 이 옵션을 사용할 때는 주의해야 합니다. |
|
액세스는 임의로 설정됩니다. 시스템에서는 이 필드를 힌트로 사용하여 파일 캐싱을 최적화할 수 있습니다.
파일 시스템에서 캐시된 I/O 및 FILE_FLAG_NO_BUFFERING 지원하지 않는 경우에는 이 플래그가 적용되지 않습니다. 자세한 내용은 이 항목의 캐싱 동작 섹션을 참조하세요. |
|
세션 인식으로 파일 또는 디바이스가 열리고 있습니다. 이 플래그를 지정하지 않으면 세션 0에서 실행되는 프로세스에서 세션별 디바이스(예: RemoteFX USB 리디렉션을 사용하는 디바이스)를 열 수 없습니다. 이 플래그는 세션 0에 없는 호출자에게는 영향을 주지 않습니다. 이 플래그는 Windows 서버 버전에서만 지원됩니다.
Windows Server 2008 R2 및 Windows Server 2008: 이 플래그는 Windows Server 2012 이전에는 지원되지 않습니다. |
|
액세스는 처음부터 끝까지 순차적으로 적용됩니다. 시스템에서는 이 필드를 힌트로 사용하여 파일 캐싱을 최적화할 수 있습니다.
읽기 숨김(즉, 이전 버전 검사)을 사용하는 경우 이 플래그를 사용하면 안 됩니다. 파일 시스템에서 캐시된 I/O 및 FILE_FLAG_NO_BUFFERING 지원하지 않는 경우에는 이 플래그가 적용되지 않습니다. 자세한 내용은 이 항목의 캐싱 동작 섹션을 참조하세요. |
|
쓰기 작업은 중간 캐시를 거치지 않고 디스크로 직접 이동합니다.
자세한 내용은 이 항목의 캐싱 동작 섹션을 참조하세요. |
dwSecurityQosFlags
dwSecurityQosFlags 매개 변수는 SQOS 정보를 지정합니다. 자세한 내용은 가장 수준을 참조하세요.
lpSecurityAttributes
별도의 두 개의 관련 데이터 멤버인 선택적 보안 설명자 및 반환된 핸들을 자식 프로세스에서 상속할 수 있는지 여부를 결정하는 부울 값이 포함된 SECURITY_ATTRIBUTES 구조체에 대한 포인터입니다.
이 매개 변수는 NULL일 수 있습니다.
이 매개 변수가 NULL인 경우 CreateFile2 에서 반환된 핸들은 애플리케이션이 만들 수 있는 자식 프로세스에서 상속할 수 없으며 반환된 핸들과 연결된 파일 또는 디바이스는 기본 보안 설명자를 가져옵니다.
구조체의 lpSecurityDescriptor 멤버는 파일 또는 디바이스에 대한 SECURITY_DESCRIPTOR 지정합니다. 이 멤버가 NULL인 경우 반환된 핸들과 연결된 파일 또는 디바이스에 기본 보안 설명자가 할당됩니다.
CreateFile2 는 기존 파일 또는 디바이스를 열 때 lpSecurityDescriptor 멤버를 무시하지만 bInheritHandle 멤버를 계속 사용합니다.
구조체의 bInheritHandle 멤버는 반환된 핸들을 상속할 수 있는지 여부를 지정합니다.
자세한 내용은 CreateFile2 항목의 설명 섹션을 참조하세요.
hTemplateFile
GENERIC_READ 액세스 권한이 있는 템플릿 파일에 대한 유효한 핸들입니다. 템플릿 파일은 생성되는 파일에 대한 파일 특성 및 확장 특성을 제공합니다.
이 매개 변수는 NULL일 수 있습니다.
기존 파일을 열 때 CreateFile2 는 이 매개 변수를 무시합니다.
암호화된 새 파일을 열 때 파일은 부모 디렉터리에서 임의 액세스 제어 목록을 상속합니다. 자세한 내용은 파일 암호화를 참조하세요.
설명
CREATEFILE2_EXTENDED_PARAMETERS 구조를 사용하는 애플리케이션을 컴파일하려면 _WIN32_WINNT 매크로 0x0602 를 이상으로 정의합니다. 자세한 내용은 Windows 헤더 사용을 참조하세요.
캐싱 동작
dwFileFlags 멤버에 대해 가능한 몇 가지 값은 핸들과 연결된 데이터가 시스템에서 캐시되는 방식을 제어하거나 영향을 미치는 데 사용됩니다. 아래에 이 계정과 키의 예제가 나와 있습니다.
- FILE_FLAG_NO_BUFFERING
- FILE_FLAG_RANDOM_ACCESS
- FILE_FLAG_SEQUENTIAL_SCAN
- FILE_FLAG_WRITE_THROUGH
- FILE_ATTRIBUTE_TEMPORARY
이러한 플래그를 지정하지 않으면 시스템은 기본 범용 캐싱 체계를 사용합니다. 그렇지 않으면 시스템 캐싱이 각 플래그에 대해 지정된 대로 동작합니다.
이러한 플래그 중 일부는 결합해서는 안 됩니다. instance FILE_FLAG_RANDOM_ACCESS FILE_FLAG_SEQUENTIAL_SCAN 결합하는 것은 자기 패배 입니다.
FILE_FLAG_SEQUENTIAL_SCAN 플래그를 지정하면 순차적 액세스를 사용하여 대용량 파일을 읽는 애플리케이션의 성능이 향상됩니다. 대용량 파일을 주로 순차적으로 읽는 애플리케이션의 경우 성능 향상이 훨씬 더 두드러질 수 있지만, 경우에 따라 작은 바이트 범위에서 앞으로 건너뜁니다. 애플리케이션이 임의 액세스를 위해 파일 포인터를 이동하는 경우 최적의 캐싱 성능이 발생하지 않을 가능성이 높습니다. 그러나 올바른 작업은 여전히 보장됩니다.
플래그 FILE_FLAG_WRITE_THROUGH 및 FILE_FLAG_NO_BUFFERING 독립적이며 결합될 수 있습니다.
FILE_FLAG_WRITE_THROUGH 사용되지만 FILE_FLAG_NO_BUFFERING 지정되지 않은 경우 시스템 캐싱이 적용되도록 데이터가 시스템 캐시에 기록되지만 지연 없이 디스크로 플러시됩니다.
시스템 캐싱이 적용되지 않도록 FILE_FLAG_WRITE_THROUGH 및 FILE_FLAG_NO_BUFFERING 모두 지정한 경우 Windows 시스템 캐시를 거치지 않고 데이터가 디스크로 즉시 플러시됩니다. 운영 체제는 또한 영구 미디어에 하드 디스크의 로컬 하드웨어 캐시의 쓰기를 요청합니다.
참고
모든 하드 디스크 하드웨어가 이 쓰기 능력을 지원하는 것은 아닙니다.
FILE_FLAG_NO_BUFFERING 플래그를 적절하게 사용하려면 특별한 애플리케이션 고려 사항이 필요합니다. 자세한 내용은 파일 버퍼링을 참조하세요.
또한 FILE_FLAG_WRITE_THROUGH 통한 쓰기 요청으로 인해 NTFS는 요청을 처리하여 발생하는 타임스탬프 업데이트 또는 이름 바꾸기 작업과 같은 메타데이터 변경 내용을 플러시합니다. 이러한 이유로 FILE_FLAG_WRITE_THROUGH 플래그는 종종 각 쓰기 후에 FlushFileBuffers 함수를 호출하는 대신 FILE_FLAG_NO_BUFFERING 플래그와 함께 사용되므로 불필요한 성능 저하가 발생할 수 있습니다. 이러한 플래그를 함께 사용하면 이러한 처벌을 피할 수 있습니다. 파일 및 메타데이터의 캐싱에 대한 일반적인 내용은 파일 캐싱을 참조하세요.
FILE_FLAG_NO_BUFFERINGFILE_FLAG_OVERLAPPED 결합하면 I/O가 메모리 관리자의 동기 작업에 의존하지 않으므로 플래그는 최대 비동기 성능을 제공합니다. 그러나 데이터가 캐시에 저장되지 않으므로 일부 I/O 작업에는 더 많은 시간이 소요됩니다. 또한 파일 메타데이터는 여전히 캐시될 수 있습니다(예: 빈 파일을 만들 때). 메타데이터가 디스크로 플러시되도록 하려면 FlushFileBuffers 함수를 사용합니다.
FILE_ATTRIBUTE_TEMPORARY 특성을 지정하면 핸들이 닫힌 후 애플리케이션이 임시 파일을 삭제하기 때문에 충분한 캐시 메모리를 사용할 수 있는 경우 파일 시스템에서 대량 스토리지에 데이터를 다시 쓰지 않도록 합니다. 이 경우 시스템은 데이터 쓰기를 완전히 방지할 수 있습니다. 앞에서 언급한 플래그와 동일한 방식으로 데이터 캐싱을 직접 제어하지는 않지만 , FILE_ATTRIBUTE_TEMPORARY 특성은 시스템에서 작성하지 않고 시스템 캐시에 가능한 한 많이 보유하도록 지시하므로 특정 애플리케이션에 문제가 될 수 있습니다.
동기 및 비동기 I/O 핸들
CreateFile2 는 동기 또는 비동기 파일 또는 디바이스 핸들을 만들기 위한 기능을 제공합니다. 동기 핸들은 해당 핸들을 사용하여 I/O 함수 호출이 완료될 때까지 차단되도록 동작하지만, 비동기 파일 핸들을 사용하면 I/O 작업을 완료했는지 여부에 관계없이 시스템이 I/O 함수 호출에서 즉시 반환할 수 있습니다. 앞에서 설명한 대로 이 동기 및 비동기 동작은 pCreateExParams 매개 변수에 전달된 CREATEFILE2_EXTENDED_PARAMETERS 구조체의 dwFileFlags 멤버 내에 FILE_FLAG_OVERLAPPED 지정하여 결정됩니다. 비동기 I/O를 사용하는 경우 몇 가지 복잡성 및 잠재적인 문제가 있습니다. 자세한 내용은 동기 및 비동기 I/O를 참조하세요.
요구 사항
| 지원되는 최소 클라이언트 | Windows 8 [데스크톱 앱 | UWP 앱] |
| 지원되는 최소 서버 | Windows Server 2012 [데스크톱 앱 | UWP 앱] |
| 머리글 | fileapi.h(Windows.h 포함) |