CreateFileFromAppW 함수(fileapifromapp.h)

파일 또는 I/O 디바이스를 만들거나 엽니다. 이 함수의 동작은 CreateFile동일하지만 이 함수는 유니버설 Windows 플랫폼 앱 보안 모델을 준수합니다.

통사론

WINSTORAGEAPI HANDLE CreateFileFromAppW(
  LPCWSTR               lpFileName,
  DWORD                 dwDesiredAccess,
  DWORD                 dwShareMode,
  LPSECURITY_ATTRIBUTES lpSecurityAttributes,
  DWORD                 dwCreationDisposition,
  DWORD                 dwFlagsAndAttributes,
  HANDLE                hTemplateFile
) noexcept;

매개 변수

lpFileName

만들거나 열 파일 또는 디바이스의 이름입니다. 이 이름에는 슬래시(/) 또는 백슬래시(\)를 사용할 수 있습니다.

이 함수의 ANSI 버전에서는 이름이 MAX_PATH 문자로 제한됩니다. 이 제한을 32,767개의 와이드 문자로 확장하려면 함수의 유니코드 버전을 호출하고 경로 앞에 "\\?\"를 추가합니다. 자세한 내용은 이름 지정 파일, 경로 및 네임스페이스참조하세요.

특수 디바이스 이름에 대한 자세한 내용은 MS-DOS 디바이스 이름정의를 참조하세요.

파일 스트림을 만들려면 파일 이름, 콜론 및 스트림의 이름을 지정합니다. 자세한 내용은 파일 스트림참조하세요.

이 함수의 유니코드 버전(CreateFileFromAppW)의 경우 "\\?\" 앞에 추가하지 않고 MAX_PATH 제한을 제거하도록 옵트인할 수 있습니다. 자세한 내용은 명명 파일, 경로 및 네임스페이스의 "최대 경로 길이 제한" 섹션을.

dwDesiredAccess

파일 또는 디바이스에 대한 요청된 액세스이며 읽기, 쓰기, 둘 다 또는 0으로 요약할 수 있습니다.

가장 일반적으로 사용되는 값은 GENERIC_READ, GENERIC_WRITE또는 둘 다(GENERIC_READ | GENERIC_WRITE)입니다. 자세한 내용은 일반 액세스 권한, 파일 보안 및 액세스 권한, 파일 액세스 권한 상수및 ACCESS_MASK참조하세요.

이 매개 변수가 0인 경우 애플리케이션은 GENERIC_READ 액세스가 거부된 경우에도 해당 파일 또는 디바이스에 액세스하지 않고 파일, 디렉터리 또는 디바이스 특성과 같은 특정 메타데이터를 쿼리할 수 있습니다.

열려 있는 핸들이 이미 있는 열린 요청에서 dwShareMode 매개 변수로 지정된 공유 모드와 충돌하는 액세스 모드를 요청할 수 없습니다.

dwShareMode

파일 또는 디바이스의 요청된 공유 모드로, 읽기, 쓰기, 모두 삭제, 이러한 모든 항목 또는 없음(다음 표 참조)입니다. 특성 또는 확장 특성에 대한 액세스 요청은 이 플래그의 영향을 받지 않습니다.

값	의미
0 0x00000000	삭제, 읽기 또는 쓰기 액세스를 요청하는 경우 다른 프로세스가 파일 또는 디바이스를 열 수 없도록 합니다.
FILE_SHARE_DELETE 0x00000004	파일 또는 디바이스에서 후속 열기 작업을 사용하여 삭제 액세스를 요청할 수 있습니다. 그렇지 않으면 삭제 액세스를 요청하는 경우 다른 프로세스에서 파일 또는 디바이스를 열 수 없습니다. 이 플래그를 지정하지 않았지만 삭제 액세스를 위해 파일 또는 디바이스가 열려 있으면 함수가 실패합니다. 참고 삭제 액세스는 삭제 및 이름 바꾸기 작업을 모두 허용합니다.
FILE_SHARE_READ 0x00000001	파일 또는 디바이스에서 후속 열기 작업을 통해 읽기 액세스를 요청할 수 있습니다. 그렇지 않으면 읽기 액세스를 요청하는 경우 다른 프로세스에서 파일 또는 디바이스를 열 수 없습니다. 이 플래그를 지정하지 않았지만 읽기 액세스를 위해 파일 또는 디바이스가 열려 있으면 함수가 실패합니다.
FILE_SHARE_WRITE 0x00000002	파일 또는 디바이스에서 후속 열기 작업을 사용하여 쓰기 액세스를 요청할 수 있습니다. 그렇지 않은 경우 다른 프로세스는 쓰기 액세스를 요청하는 경우 파일 또는 디바이스를 열 수 없습니다. 이 플래그를 지정하지 않았지만 파일 또는 디바이스가 쓰기 액세스를 위해 열렸거나 쓰기 액세스 권한이 있는 파일 매핑이 있는 경우 함수가 실패합니다.

lpSecurityAttributes

별도의 두 개의 관련 데이터 멤버인 선택적 보안 설명자 및 반환된 핸들을 자식 프로세스에서 상속할 수 있는지 여부를 결정하는 부울 값이 포함된 SECURITY_ATTRIBUTES 구조체에 대한 포인터입니다.

이 매개 변수는 NULL수 있습니다.

이 매개 변수가 NULL경우 반환된 핸들은 애플리케이션이 만들 수 있는 자식 프로세스에서 상속할 수 없으며 반환된 핸들과 연결된 파일 또는 디바이스는 기본 보안 설명자를 가져옵니다.

구조체의 lpSecurityDescriptor 멤버는 파일 또는 디바이스에 대한 SECURITY_DESCRIPTOR 지정합니다. 이 멤버가 NULL경우 반환된 핸들과 연결된 파일 또는 디바이스에 기본 보안 설명자가 할당됩니다.

이 함수는 기존 파일 또는 디바이스를 열 때 lpSecurityDescriptor 멤버를 무시하지만 bInheritHandle 멤버를 계속 사용합니다.

구조체의 bInheritHandle 멤버는 반환된 핸들을 상속할 수 있는지 여부를 지정합니다.

dwCreationDisposition

존재하거나 존재하지 않는 파일 또는 디바이스에서 수행할 작업입니다.

파일 이외의 디바이스의 경우 이 매개 변수는 일반적으로 OPEN_EXISTING.

자세한 내용은 설명 섹션을 참조하세요.

이 매개 변수는 결합할 수 없는 다음 값 중 하나여야 합니다.

값	의미
CREATE_ALWAYS 2	항상 새 파일을 만듭니다. 지정된 파일이 존재하고 쓰기 가능한 경우 함수는 파일을 잘라내고, 함수가 성공하며, 마지막 오류 코드가 ERROR_ALREADY_EXISTS(183)로 설정됩니다. 지정한 파일이 존재하지 않고 유효한 경로인 경우 새 파일이 만들어지고 함수가 성공하며 마지막 오류 코드가 0으로 설정됩니다. 자세한 내용은 이 항목의 설명 섹션을 참조하세요.
CREATE_NEW 1	새 파일이 없는 경우에만 새 파일을 만듭니다. 지정된 파일이 있으면 함수가 실패하고 마지막 오류 코드가 ERROR_FILE_EXISTS(80)로 설정됩니다. 지정한 파일이 존재하지 않고 쓰기 가능한 위치에 대한 유효한 경로인 경우 새 파일이 만들어집니다.
OPEN_ALWAYS 4	항상 파일을 엽니다. 지정된 파일이 있으면 함수가 성공하고 마지막 오류 코드가 ERROR_ALREADY_EXISTS(183)로 설정됩니다. 지정된 파일이 존재하지 않고 쓰기 가능한 위치에 대한 유효한 경로인 경우 함수는 파일을 만들고 마지막 오류 코드는 0으로 설정됩니다.
OPEN_EXISTING 3	파일이 있는 경우에만 파일 또는 디바이스를 엽니다. 지정된 파일 또는 디바이스가 없으면 함수가 실패하고 마지막 오류 코드가 ERROR_FILE_NOT_FOUND(2)로 설정됩니다. 디바이스에 대한 자세한 내용은 설명 섹션을 참조하세요.
TRUNCATE_EXISTING 5	파일을 열고 파일이 있는 경우에만 크기가 0바이트가 되도록 자른다. 지정된 파일이 없으면 함수가 실패하고 마지막 오류 코드가 ERROR_FILE_NOT_FOUND(2)로 설정됩니다. 호출 프로세스는 GENERIC_WRITE 비트가 dwDesiredAccess 매개 변수의 일부로 설정된 파일을 열어야 합니다.

dwFlagsAndAttributes

파일 또는 디바이스 특성 및 플래그이며, FILE_ATTRIBUTE_NORMAL 파일의 가장 일반적인 기본값입니다.

이 매개 변수는 사용 가능한 파일 특성(FILE_ATTRIBUTE_*)의 조합을 포함할 수 있습니다. 다른 모든 파일 특성은 FILE_ATTRIBUTE_NORMAL재정의합니다.

이 매개 변수는 파일 또는 디바이스 캐싱 동작, 액세스 모드 및 기타 특수 용도 플래그를 제어하기 위한 플래그(FILE_FLAG_*)의 조합을 포함할 수도 있습니다. 이러한 값은 모든 FILE_ATTRIBUTE_* 값과 결합됩니다.

이 매개 변수는 SECURITY_SQOS_PRESENT 플래그를 지정하여 SQOS(보안 서비스 품질) 정보를 포함할 수도 있습니다. 추가 SQOS 관련 플래그 정보는 특성 및 플래그 테이블 다음에 테이블에 표시됩니다.

속성	의미
FILE_ATTRIBUTE_ARCHIVE 32(0x20)	파일을 보관해야 합니다. 애플리케이션은 이 특성을 사용하여 백업 또는 제거를 위해 파일을 표시합니다.
FILE_ATTRIBUTE_ENCRYPTED 16384(0x4000)	파일 또는 디렉터리가 암호화됩니다. 파일의 경우 이는 파일의 모든 데이터가 암호화됨을 의미합니다. 디렉터리의 경우 암호화가 새로 만든 파일 및 하위 디렉터리의 기본값임을 의미합니다. 자세한 내용은 파일 암호화참조하세요. FILE_ATTRIBUTE_SYSTEM 지정한 경우에도 이 플래그는 적용되지 않습니다. 이 플래그는 Windows의 Home, Home Premium, Starter 또는 ARM 버전에서 지원되지 않습니다.
FILE_ATTRIBUTE_HIDDEN 2(0x2)	파일이 숨겨져 있습니다. 일반 디렉터리 목록에 포함하지 마세요.
FILE_ATTRIBUTE_NORMAL 128(0x80)	파일에 다른 특성 집합이 없습니다. 이 특성은 단독으로 사용하는 경우에만 유효합니다.
FILE_ATTRIBUTE_OFFLINE 4096(0x1000)	파일의 데이터를 즉시 사용할 수 없습니다. 이 특성은 파일 데이터가 오프라인 스토리지로 물리적으로 이동되었음을 나타냅니다. 이 특성은 계층적 스토리지 관리 소프트웨어인 Remote Storage에서 사용됩니다. 애플리케이션은 이 특성을 임의로 변경해서는 안 됩니다.
FILE_ATTRIBUTE_READONLY 1(0x1)	파일은 읽기 전용입니다. 애플리케이션은 파일을 읽을 수 있지만 파일을 쓰거나 삭제할 수는 없습니다.
FILE_ATTRIBUTE_SYSTEM 4(0x4)	이 파일은 운영 체제의 일부이거나 단독으로 사용됩니다.
FILE_ATTRIBUTE_TEMPORARY 256(0x100)	파일이 임시 스토리지에 사용되고 있습니다. 자세한 내용은 이 항목의 캐싱 동작 섹션을 참조하세요.

 

기	의미
FILE_FLAG_BACKUP_SEMANTICS 0x02000000	백업 또는 복원 작업을 위해 파일을 열거나 만듭니다. 시스템은 프로세스에 SE_BACKUP_NAME 및 SE_RESTORE_NAME 권한이 있는 경우 호출 프로세스가 파일 보안 검사를 재정의하도록 합니다. 자세한 내용은 토큰변경 권한을 참조하세요. 디렉터리에 대한 핸들을 가져오려면 이 플래그를 설정해야 합니다. 디렉터리 핸들은 파일 핸들 대신 일부 함수에 전달할 수 있습니다. 자세한 내용은 설명 섹션을 참조하세요.
FILE_FLAG_DELETE_ON_CLOSE 0x04000000	지정된 핸들 및 기타 열려 있거나 중복된 핸들을 포함하는 모든 핸들이 닫힌 직후에 파일이 삭제됩니다. 파일에 열려 있는 기존 핸들이 있는 경우 FILE_SHARE_DELETE 공유 모드로 열려 있지 않으면 호출이 실패합니다. FILE_SHARE_DELETE 공유 모드를 지정하지 않으면 파일에 대한 후속 열린 요청이 실패합니다.
FILE_FLAG_NO_BUFFERING 0x20000000	파일 또는 디바이스가 데이터 읽기 및 쓰기에 대한 시스템 캐싱 없이 열리고 있습니다. 이 플래그는 하드 디스크 캐싱 또는 메모리 매핑된 파일에 영향을 주지 않습니다. FILE_FLAG_NO_BUFFERING 플래그를 사용하여 이 함수로 열린 파일을 성공적으로 사용하기 위한 엄격한 요구 사항이 있습니다. 자세한 내용은 파일 버퍼링참조하세요.
FILE_FLAG_OPEN_NO_RECALL 0x00100000	파일 데이터가 요청되지만 원격 스토리지에 계속 위치해야 합니다. 로컬 스토리지로 다시 전송해서는 안 됩니다. 이 플래그는 원격 스토리지 시스템에서 사용하기 위한 것입니다.
FILE_FLAG_OPEN_REPARSE_POINT 0x00200000	일반 재설정 지점 처리는 발생하지 않습니다. 이 함수는 재 분석 지점을 열려고 시도합니다. 파일을 열면 재설정 지점을 제어하는 필터가 작동하는지 여부에 관계없이 파일 핸들이 반환됩니다. 이 플래그는 CREATE_ALWAYS 플래그와 함께 사용할 수 없습니다. 파일이 재조사 지점이 아니면 이 플래그는 무시됩니다. 자세한 내용은 설명 섹션을 참조하세요.
FILE_FLAG_OVERLAPPED 0x40000000	파일 또는 디바이스가 비동기 I/O용으로 열리거나 생성되고 있습니다. 이 핸들에서 후속 I/O 작업이 완료되면 OVERLAPPED 구조에 지정된 이벤트가 신호 상태로 설정됩니다. 이 플래그를 지정하면 파일을 동시 읽기 및 쓰기 작업에 사용할 수 있습니다. 이 플래그를 지정하지 않으면 읽기 및 쓰기 함수에 대한 호출이 OVERLAPPED 구조를 지정하더라도 I/O 작업이 serialize됩니다. 이 플래그로 만든 파일 핸들을 사용하는 경우의 고려 사항에 대한 자세한 내용은 이 항목의 동기 및 비동기 I/O 핸들 섹션을 참조하세요.
FILE_FLAG_POSIX_SEMANTICS 0x0100000	액세스는 POSIX 규칙에 따라 발생합니다. 여기에는 해당 이름을 지원하는 파일 시스템에 대해서만 이름이 다른 여러 파일을 허용하는 것이 포함됩니다. 이 플래그로 만든 파일은 MS-DOS 또는 16비트 Windows용으로 작성된 애플리케이션에서 액세스할 수 없으므로 이 옵션을 사용할 때는 주의해야 합니다.
FILE_FLAG_RANDOM_ACCESS 0x10000000	액세스는 임의로 의도됩니다. 시스템은 이를 힌트로 사용하여 파일 캐싱을 최적화할 수 있습니다. 파일 시스템에서 캐시된 I/O 및 FILE_FLAG_NO_BUFFERING지원하지 않는 경우에는 이 플래그가 적용되지 않습니다. 자세한 내용은 이 항목의 캐싱 동작 섹션을 참조하세요.
FILE_FLAG_SESSION_AWARE 0x00800000	세션 인식으로 파일 또는 디바이스를 열고 있습니다. 이 플래그를 지정하지 않으면 세션 0에서 실행되는 프로세스에서 세션별 디바이스(예: RemoteFX USB 리디렉션을 사용하는 디바이스)를 열 수 없습니다. 이 플래그는 세션 0에 없는 호출자에게는 영향을 주지 않습니다. 이 플래그는 Windows 서버 버전에서만 지원됩니다.
FILE_FLAG_SEQUENTIAL_SCAN 0x08000000	액세스는 처음부터 끝까지 순차적으로 적용됩니다. 시스템은 이를 힌트로 사용하여 파일 캐싱을 최적화할 수 있습니다. 읽기 숨김(즉, 역방향 검사)을 사용하는 경우 이 플래그를 사용하면 안 됩니다. 파일 시스템에서 캐시된 I/O 및 FILE_FLAG_NO_BUFFERING지원하지 않는 경우에는 이 플래그가 적용되지 않습니다. 자세한 내용은 이 항목의 캐싱 동작 섹션을 참조하세요.
FILE_FLAG_WRITE_THROUGH 0x80000000	쓰기 작업은 중간 캐시를 거치지 않고 디스크로 직접 이동합니다. 자세한 내용은 이 항목의 캐싱 동작 섹션을 참조하세요.

 

dwFlagsAndAttributes매개 변수는 SQOS 정보를 지정할 수도 있습니다. 자세한 내용은 가장 수준참조하세요. 호출 애플리케이션이 dwFlagsAndAttributes일부로 SECURITY_SQOS_PRESENT 플래그를 지정하는 경우 다음 값 중 하나 이상을 포함할 수도 있습니다.

보안 플래그	의미
SECURITY_ANONYMOUS	익명 가장 수준에서 클라이언트를 가장합니다.
SECURITY_CONTEXT_TRACKING	보안 추적 모드는 동적입니다. 이 플래그를 지정하지 않으면 보안 추적 모드가 정적입니다.
SECURITY_DELEGATION	위임 가장 수준에서 클라이언트를 가장합니다.
SECURITY_EFFECTIVE_ONLY	클라이언트 보안 컨텍스트의 활성화된 측면만 서버에서 사용할 수 있습니다. 이 플래그를 지정하지 않으면 클라이언트 보안 컨텍스트의 모든 측면을 사용할 수 있습니다. 이렇게 하면 클라이언트가 클라이언트를 가장하는 동안 서버에서 사용할 수 있는 그룹 및 권한을 제한할 수 있습니다.
SECURITY_IDENTIFICATION	ID 가장 수준에서 클라이언트를 가장합니다.
SECURITY_IMPERSONATION	가장 수준에서 클라이언트를 가장합니다. SECURITY_SQOS_PRESENT 플래그와 함께 다른 플래그가 지정되지 않은 경우 기본 동작입니다.

hTemplateFile

GENERIC_READ 액세스 권한이 있는 템플릿 파일에 대한 유효한 핸들입니다. 템플릿 파일은 생성되는 파일에 대한 파일 특성 및 확장 특성을 제공합니다.

이 매개 변수는 NULL수 있습니다.

기존 파일을 열 때 이 매개 변수는 무시됩니다.

암호화된 새 파일을 열 때 파일은 부모 디렉터리에서 임의 액세스 제어 목록을 상속합니다. 자세한 내용은 파일 암호화참조하세요.

반환 값

함수가 성공하면 반환 값은 지정된 파일, 디바이스, 명명된 파이프 또는 메일 슬롯에 대한 열린 핸들입니다.

함수가 실패하면 반환 값이 INVALID_HANDLE_VALUE. 확장 오류 정보를 얻으려면 GetLastError호출합니다.

요구 사항

요구	값
지원되는 최소 클라이언트	Windows 10 버전 1803
헤더	fileapifromapp.h