SetupInstallFileExA 함수(setupapi.h)
[이 함수는 요구 사항 섹션에 표시된 운영 체제에서 사용할 수 있습니다. 이후 버전에서는 변경되거나 제공되지 않을 수 있습니다. SetupAPI는 더 이상 애플리케이션 설치에 사용되지 않아야 합니다. 대신 Windows Installer를 사용하여 애플리케이션 설치 관리자를 개발합니다. SetupAPI는 디바이스 드라이버를 설치하는 데 계속 사용됩니다.]
SetupInstallFileEx 함수는 SetupFindXXXLine에서 반환된 INFCONTEXT에서 지정한 대로 또는 파일 이름 및 경로 정보로 명시적으로 파일을 설치합니다. 이 함수는 파일이 사용 중인지 여부를 나타내는 BOOL이 반환된다는 점을 제외하고 SetupInstallFile과 동일합니다.
파일이 복사되면 이 함수의 호출자는 대상 디렉터리에 쓸 수 있는 권한이 있어야 합니다.
구문
WINSETUPAPI BOOL SetupInstallFileExA(
[in] HINF InfHandle,
[in] PINFCONTEXT InfContext,
[in] PCSTR SourceFile,
[in] PCSTR SourcePathRoot,
[in] PCSTR DestinationName,
[in] DWORD CopyStyle,
[in] PSP_FILE_CALLBACK_A CopyMsgHandler,
[in] PVOID Context,
[out] PBOOL FileWasInUse
);
매개 변수
[in] InfHandle
SourceDisksNames 및 SourceDisksFiles 섹션이 포함된 INF 파일에 대한 핸들에 대한 선택적 포인터입니다. 사용자 시스템에 대한 플랫폼별 섹션(예: SourceDisksNames.x86 및 SourceDisksFiles.x86)이 있는 경우 플랫폼별 섹션이 사용됩니다. InfContext를 지정하지 않고 CopyStyle에 SP_COPY_SOURCE_ABSOLUTE 또는 SP_COPY_SOURCEPATH_ABSOLUTE 포함된 경우 InfHandle은 무시됩니다.
[in] InfContext
INF 파일의 파일 복사 섹션에 있는 줄의 컨텍스트에 대한 선택적 포인터입니다. 루틴은 InfHandle 의 SourceDisksFiles 섹션에서 이 파일을 조회하여 파일 복사 정보를 가져옵니다. InfContext가 지정되지 않은 경우 SourceFile은 이어야 합니다.
[in] SourceFile
복사할 파일의 파일 이름(경로 없음)에 대한 선택적 포인터입니다. 파일은 SourceDisksFiles 섹션에서 조회됩니다. InfContext가 아닌 경우 SourceFile 매개 변수를 지정해야 합니다. 그러나 InfContext를 지정하면 SourceFile이 무시됩니다.
[in] SourcePathRoot
복사할 파일의 루트 경로에 대한 선택적 포인터입니다(예: A:\ 또는 F:). SourceDisksNames 섹션의 경로가 이 경로에 추가됩니다. CopyStyle에 SP_COPY_SOURCE_ABSOLUTE 플래그가 포함된 경우 SourcePathRoot 매개 변수는 무시됩니다.
[in] DestinationName
복사한 파일의 새 이름에 대한 선택적 포인터입니다. InfContext를 지정하면 DestinationName은 대상 파일의 파일 이름만(경로 없음)을 제공합니다. 이 매개 변수는 대상 파일의 이름이 원본 파일과 동일해야 함을 나타내는 NULL 일 수 있습니다. InfContext를 지정하지 않으면 DestinationName은 대상의 전체 대상 경로와 파일 이름을 제공합니다.
[in] CopyStyle
파일 복사 작업의 동작을 제어하는 플래그입니다.
이러한 플래그는 다음 값의 조합일 수 있습니다.
| 값 | 의미 |
|---|---|
|
복사에 성공하면 원본 파일을 삭제합니다. 삭제가 실패하면 호출자에게 알림이 표시되지 않습니다. |
|
이렇게 하면 대상 경로에서 파일을 덮어쓰는 경우에만 파일을 복사합니다. |
|
복사되는 각 파일을 검사하여 해당 버전 리소스가 대상의 기존 복사본과 동일하거나 최신 버전이 아닌지 확인합니다.
버전 검사 중에 사용되는 파일 버전 정보는 버전 함수가 입력한 대로 VS_FIXEDFILEINFO 구조체의 dwFileVersionMS 및 dwFileVersionLS 멤버에 지정된 것입니다. 파일 중 하나에 버전 리소스가 없거나 버전 정보가 동일한 경우 원본 파일은 최신 버전으로 간주됩니다. 원본 파일이 최신 버전이 아니거나 같고 CopyMsgHandler 가 지정된 경우 호출자에게 알림이 표시되고 복사본을 취소할 수 있습니다. CopyMsgHandler를 지정하지 않으면 파일이 복사되지 않습니다. |
|
복사되는 각 파일을 검사하여 해당 버전 리소스가 대상의 기존 복사본보다 최신이 아님을 나타내는지 확인합니다. 원본 파일이 최신 버전이지만 버전이 기존 대상과 같지 않으면 파일이 복사됩니다. |
|
대상 파일이 있는지 확인하고, 있는 경우 복사본을 거부할 수 있는 호출자에게 알립니다. CopyMsgHandler를 지정하지 않으면 파일을 덮어쓰지 않습니다. |
|
파일의 압축을 풀지 마세요. 이 플래그를 설정하면 대상 파일에 소스 이름의 압축되지 않은 형식(해당하는 경우)이 제공되지 않습니다. 예를 들어 "f:\x86\cmd.ex_"을 "\\install\temp"로 복사하면 대상 파일 "\\install\temp\cmd.ex_"이 생성됩니다. SP_COPY_NODECOMP 플래그를 지정하지 않으면 파일의 압축이 해제되고 대상을 "\\install\temp\cmd.exe"이라고 합니다. DestinationName의 파일 이름 부분(지정된 경우)이 제거되고 원본 파일의 파일 이름으로 대체됩니다. SP_COPY_NODECOMP 지정하면 언어 또는 버전 정보를 확인할 수 없습니다. |
|
복사되는 각 파일을 검사하여 해당 언어가 대상에 이미 있는 기존 파일의 언어와 다른지 확인합니다. 이 경우 CopyMsgHandler 가 지정되면 호출자에게 알림이 표시되고 복사본을 취소할 수 있습니다. CopyMsgHandler를 지정하지 않으면 파일이 복사되지 않습니다. |
|
SourceFile 은 전체 원본 경로입니다. INF 파일의 SourceDisksNames 섹션에서 조회하지 마세요. |
|
SourcePathRoot 는 원본 파일의 전체 경로 부분입니다. 파일이 있는 원본 미디어에 대한 INF 파일의 SourceDisksNames 섹션에 지정된 상대 원본을 무시합니다. SP_COPY_SOURCE_ABSOLUTE 지정된 경우 이 플래그는 무시됩니다. |
|
대상이 있는 경우 사용 중인 것처럼 동작하고 다음 시스템 다시 부팅에서 복사할 파일을 큐에 대기합니다. |
|
복사 작업 중에 파일이 사용 중이면 시스템을 다시 부팅해야 한다는 사실을 사용자에게 알립니다. |
|
사용자에게 파일을 건너뛸 수 있는 옵션을 제공하지 마세요. |
|
대상 파일이 있는지 확인하고, 있는 경우 파일을 덮어쓰지 않습니다. 호출자에게 알림이 표시되지 않습니다. |
|
복사되는 각 파일을 검사하여 해당 버전 리소스(또는 이미지가 아닌 파일의 타임스탬프는)가 대상의 기존 복사본보다 최신이 아님을 나타내는지 확인합니다. 복사 중인 파일이 최신 파일이 아니면 파일이 복사되지 않습니다. 호출자에게 알림이 표시되지 않습니다. |
|
사용자가 파일을 건너뛰려고 하면 파일을 건너뛰는 것이 설치에 영향을 줄 수 있음을 경고합니다. (시스템에 중요한 파일에 사용됩니다.) |
[in] CopyMsgHandler
파일 복사 중에 발생할 수 있는 다양한 조건에 대한 알림을 받을 콜백 함수에 대한 선택적 포인터입니다.
[in] Context
콜백 함수의 첫 번째 매개 변수로 전달되는 호출자 정의 값에 대한 포인터입니다.
[out] FileWasInUse
이 함수가 파일이 사용 중인지 여부를 나타내는 플래그를 반환하는 변수에 대한 포인터입니다. 이 매개 변수는 필수입니다.
반환 값
함수가 성공하면 반환 값은 0이 아닌 값입니다.
함수가 실패하면 반환 값은 0입니다. 확장 오류 정보를 가져오려면 GetLastError를 호출합니다.
GetLastError가 NO_ERROR 반환하는 경우 파일 복사 작업이 완료되지 않았습니다. 파일 복사 작업이 필요하지 않았거나 파일 콜백 함수가 FALSE를 반환했기 때문에 파일이 복사되지 않았을 수 있습니다.
설명
이 API는 일반적으로 사용 중일 가능성이 있는 새 버전의 시스템 파일을 설치할 때 사용됩니다. 파일이 사용 중인지 여부를 나타내는 BOOL 값을 업데이트합니다. 파일이 사용 중이면 시스템이 다시 부팅될 때까지 파일 복사 작업이 연기됩니다.
UNC 디렉터리가 파일 설치의 대상 디렉터리로 지정된 경우 SetupInstallFileEx를 호출하기 전에 해당 디렉터리가 있는지 확인해야 합니다. 설치 함수는 가 있는지 검사 않으며 UNC 디렉터리를 만들지 않습니다. 대상 UNC 디렉터리가 없으면 파일 설치가 실패합니다.
참고
setupapi.h 헤더는 SETUPInstallFileEx를 유니코드 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입에 대한 규칙을 참조하세요.
요구 사항
| 요구 사항 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Windows XP [데스크톱 앱만 해당] |
| 지원되는 최소 서버 | Windows Server 2003 [데스크톱 앱만 해당] |
| 대상 플랫폼 | Windows |
| 헤더 | setupapi.h |
| 라이브러리 | Setupapi.lib |
| DLL | Setupapi.dll |
참조
피드백
출시 예정: 2024년 내내 콘텐츠에 대한 피드백 메커니즘으로 GitHub 문제를 단계적으로 폐지하고 이를 새로운 피드백 시스템으로 바꿀 예정입니다. 자세한 내용은 다음을 참조하세요. https://aka.ms/ContentUserFeedback
다음에 대한 사용자 의견 제출 및 보기