Функция SetupInstallFileExA (setupapi.h)

Статья
11/20/2024

[Эта функция доступна для использования в операционных системах, указанных в разделе "Требования". Он может быть изменен или недоступен в последующих версиях. SetupAPI больше не следует использовать для установки приложений. Вместо этого используйте установщик Windows для разработки установщиков приложений. SetupAPI по-прежнему используется для установки драйверов устройств.]

Функция setupInstallFileEx устанавливает файл, указанный INFCONTEXT, возвращаемой SetupFindXXXXLine или явным образом по имени файла и данным пути. Эта функция совпадает с SetupInstallFile, за исключением того, что возвращается BOOL, указывающее, был ли используемый файл.

Если файл копируется, вызывающий эту функцию должен иметь права на запись в целевой каталог.

Синтаксис

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

Необязательный указатель на дескриптор в INF-файл, содержащий разделы SourceDisksNames и SourceDisksFiles. Если для системы пользователя существуют разделы для конкретной платформы (например, SourceDisksNames.x86 и SourceDisksFiles.x86), используется раздел, зависящий от платформы. Если InfContext не указан и CopyStyle включает SP_COPY_SOURCE_ABSOLUTE или SP_COPY_SOURCEPATH_ABSOLUTE, InfHandle игнорируется.

[in] InfContext

Необязательный указатель на контекст строки в разделе "Файлы копирования" в INF-файле. Подпрограмма ищет этот файл в разделе SourceDisksFiles InfHandle, чтобы получить сведения о копировании файлов. Если InfContext не указано, необходимо SourceFile.

[in] SourceFile

Необязательный указатель на имя файла (без пути) копируемого файла. Файл ищется в разделе SourceDisksFiles. Параметр SourceFile необходимо указать, если InfContext нет. Однако SourceFile игнорируется, если указан InfContext.

[in] SourcePathRoot

Необязательный указатель на корневой путь для копирования файла (например, A:\ или F:). Пути в разделе SourceDisksNames добавляются к этому пути. Параметр SourcePathRoot игнорируется, если CopyStyle включает флаг SP_COPY_SOURCE_ABSOLUTE.

[in] DestinationName

Необязательный указатель на новое имя скопированного файла. Если указан InfContext, DestinationName предоставляет только имя файла (без пути) целевого файла. Этот параметр может быть значение NULL, чтобы указать, что целевой файл должен иметь то же имя, что и исходный файл. Если InfContext не задано, DestinationName предоставляет полный целевой путь и имя файла для целевого объекта.

[in] CopyStyle

Флаги, управляющие поведением операции копирования файлов.

Эти флаги могут быть сочетанием следующих значений.

Ценность	Значение
SP_COPY_DELETESOURCE	Удалите исходный файл после успешной копии. Вызывающий объект не уведомляется, если удаление завершается ошибкой.
SP_COPY_REPLACEONLY	Скопируйте файл, только если это перезаписывает файл по пути назначения.
SP_COPY_NEWER_OR_SAME	Проверьте каждый файл, копируемый, чтобы узнать, указывает ли его ресурсы версии на то, что она является той же версией или не более новой, чем существующая копия в целевом объекте. Сведения о версии файла, используемые во время проверок версий, указываются в dwFileVersionMS и dwFileVersionLS членов структуры VS_FIXEDFILEINFO, как указано в функциях версии. Если у одного из файлов нет ресурсов версии или если они имеют идентичные сведения о версии, исходный файл считается более новым. Если исходный файл не является более новым или равным в версии, а указана CopyMsgHandler, вызывающий объект уведомляется и может отменить копию. Если CopyMsgHandler не указан, файл не копируется.
SP_COPY_NEWER_ONLY	Проверьте каждый файл, копируемый, чтобы узнать, являются ли его ресурсы версии более новой, чем существующую копию в целевом объекте. Если исходный файл является более новым, но не равен в версии существующего целевого объекта, файл копируется.
SP_COPY_NOOVERWRITE	Проверьте, существует ли целевой файл, и если да, уведомите вызывающего абонента, который может ветоить копию. Если CopyMsgHandler не указан, файл не перезаписывается.
SP_COPY_NODECOMP	Не распаковывайте файл. Если этот флаг задан, целевой файл не получает несжатую форму исходного имени (при необходимости). Например, копирование "f:\x86\cmd.ex_" в "\\install\temp" приводит к целевому файлу "\\install\temp\cmd.ex_". Если флаг SP_COPY_NODECOMP не указан, файл будет декомпрессирован, а целевой объект будет называться "\\install\temp\cmd.exe". Часть имени файла DestinationName, если указано, удаляется и заменяется именем файла исходного файла. При указании SP_COPY_NODECOMP нет сведений о языке или версии.
SP_COPY_LANGUAGEAWARE	Изучите каждый файл, копируемый, чтобы узнать, отличается ли его язык от языка любого существующего файла, уже размещенного в целевом объекте. Если это так, и указана CopyMsgHandler, вызывающий объект уведомляется и может отменить копию. Если CopyMsgHandler не указан, файл не копируется.
SP_COPY_SOURCE_ABSOLUTE	SourceFile — это полный путь к источнику. Не ищите его в разделе SourceDisksNames в INF-файле.
SP_COPY_SOURCEPATH_ABSOLUTE	SourcePathRoot является полной частью исходного файла. Игнорируйте относительный источник, указанный в разделе SourceDisksNames в INF-файле исходного носителя, где находится файл. Этот флаг игнорируется, если указан SP_COPY_SOURCE_ABSOLUTE.
SP_COPY_FORCE_IN_USE	Если целевой объект существует, ведет себя так, как будто он используется и помещается в очередь файла для копирования на следующую перезагрузку системы.
SP_COPY_IN_USE_NEEDS_REBOOT	Если файл использовался во время операции копирования, сообщите пользователю, что системе требуется перезагрузка.
SP_COPY_NOSKIP	Не предоставляйте пользователю возможность пропускать файл.
SP_COPY_FORCE_NOOVERWRITE	Проверьте, существует ли целевой файл и если да, файл не перезаписан. Вызывающий объект уведомляется.
SP_COPY_FORCE_NEWER	Просмотрите каждый файл, копируемый, чтобы узнать, являются ли его ресурсы версии (или метки времени для файлов, не являющихся изображениями), что это не более новая копия в целевом объекте. Если копируемый файл не является более новым, файл не копируется. Вызывающий объект уведомляется.
SP_COPY_WARNIFSKIP	Если пользователь пытается пропустить файл, предупредите их о том, что пропуск файла может повлиять на установку. (Используется для системных критически важных файлов.)

[in] CopyMsgHandler

Необязательный указатель на функцию обратного вызова, которая может быть уведомлена о различных условиях, которые могут возникнуть во время копирования файла.

[in] Context

Указатель на определяемое вызывающим значением, которое передается в качестве первого параметра функции обратного вызова.

[out] FileWasInUse

Указатель на переменную, в которой эта функция возвращает флаг, указывающий, используется ли файл. Этот параметр является обязательным.

Возвращаемое значение

Если функция выполнена успешно, возвращаемое значение является ненулевое значение.

Если функция завершается ошибкой, возвращаемое значение равно нулю. Чтобы получить расширенные сведения об ошибке, вызовите GetLastError.

Если GetLastError возвращает NO_ERROR, операция копирования файлов не завершена. Возможно, файл не был скопирован, так как операция копирования файлов была ненужной или так как функция обратного вызова файла вернула FALSE.

Замечания

Этот API обычно используется при установке новых версий системных файлов, которые, скорее всего, будут использоваться. Он обновляет значение boOL, указывающее, используется ли файл. Если файл использовался, операция копирования файлов откладывается до перезагрузки системы.

Если каталог UNC указан в качестве целевого каталога установки файла, перед вызовом SetupInstallFileExнеобходимо убедиться, что он существует. Функции установки не проверяют наличие и не создают каталоги UNC. Если целевой каталог UNC не существует, установка файла завершается ошибкой.

Заметка

Заголовок setupapi.h определяет SetupInstallFileEx как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows XP [только классические приложения]
минимальный поддерживаемый сервер	Windows Server 2003 [только классические приложения]
целевая платформа	Виндоус
заголовка	setupapi.h
библиотеки	Setupapi.lib
DLL	Setupapi.dll