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

Статья
08/26/2023

[Эта функция доступна для использования в операционных системах, указанных в разделе Требования. В последующих версиях он может быть изменен или недоступен. 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

Необязательный указатель на контекст для строки в разделе Copy Files в 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 [только классические приложения]
Целевая платформа	Windows
Header	setupapi.h
Библиотека	Setupapi.lib
DLL	Setupapi.dll