Функция SetupInstallFileW (setupapi.h)
[Эта функция доступна для использования в операционных системах, указанных в разделе Требования. В последующих версиях он может быть изменен или недоступен. SetupAPI больше не следует использовать для установки приложений. Вместо этого используйте установщик Windows для разработки установщиков приложений. SetupAPI по-прежнему используется для установки драйверов устройств.]
Функция SetupInstallFile устанавливает файл в соответствии с указанием INFCONTEXT , возвращаемого Командой SetupFindXXXLine, или явным образом по имени файла и пути.
При копировании файла вызывающий объект этой функции должен иметь права записи в целевой каталог.
Синтаксис
WINSETUPAPI BOOL SetupInstallFileW(
[in] HINF InfHandle,
[in] PINFCONTEXT InfContext,
[in] PCWSTR SourceFile,
[in] PCWSTR SourcePathRoot,
[in] PCWSTR DestinationName,
[in] DWORD CopyStyle,
[in] PSP_FILE_CALLBACK_W CopyMsgHandler,
[in] PVOID Context
);
Параметры
[in] InfHandle
Необязательный указатель на дескриптор INF-файла, который содержит разделы SourceDisksNames и SourceDisksFiles. Если для системы пользователя существуют разделы, зависящие от платформы (например, SourceDisksNames.x86 и SourceDisksFiles.x86), будет использоваться раздел для конкретной платформы. Если параметр InfContext имеет значение NULL и CopyStyle включает SP_COPY_SOURCE_ABSOLUTE или SP_COPY_SOURCEPATH_ABSOLUTE, InfHandle игнорируется.
[in] InfContext
Необязательный указатель на контекст строки в разделе Copy Files в INF-файле. Подпрограмма ищет этот файл в разделе SourceDisksFiles раздела InfHandle , чтобы получить сведения о копировании файла. Если InfHandle не указан, параметр SourceFile должен иметь значение .
[in] SourceFile
Необязательный указатель на имя файла (без пути) копируемого файла. Файл можно найти в разделе SourceDisksFiles. Параметр SourceFile должен быть указан, если параметр InfContext не задан. Параметр SourceFile игнорируется, если указан параметр InfContext .
[in] SourcePathRoot
Необязательный указатель на корневой путь к копируемым файлам (например, A:\ или F:). К этому пути добавляются пути в разделе SourceDisksNames. Параметр SourcePathRoot игнорируется, если CopyStyle содержит флаг SP_COPY_SOURCE_ABSOLUTE.
[in] DestinationName
Необязательный указатель только на имя файла (без пути) к целевому файлу. Этот параметр может иметь значение NULL, чтобы указать, что целевой файл должен иметь то же имя, что и исходный файл. Если Параметр InfContext не указан, DestinationName предоставляет полный путь и имя файла для целевого объекта.
[in] CopyStyle
Флаги, управляющие поведением операции копирования файлов. Эти флаги могут быть комбинацией следующих значений.
| Значение | Значение |
|---|---|
|
Удаляет исходный файл после успешного копирования. Вызывающий объект не получает уведомления, если операция удаления завершается сбоем. |
|
Копирует файл только в том случае, если это приведет к перезаписи файла по целевому пути. Если целевой объект не существует, функция возвращает ЗНАЧЕНИЕ FALSE , а GetLastError возвращает NO_ERROR. |
|
Проверяет каждый копируемый файл, чтобы узнать, указывают ли его версии ресурсы на то, что он имеет ту же версию или не новее, чем существующая копия на целевом объекте.
Сведения о версии файла, используемые при проверке версии, указываются в членах dwFileVersionMS и dwFileVersionLSструктуры VS_FIXEDFILEINFO , как указано в функциях версии. Если у одного из файлов нет ресурсов версии или они содержат идентичные сведения о версии, исходный файл считается более новым. Если исходный файл не является более новым или не равен по версии и указан параметр 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 — это полный путь к исходному коду. Не ищите его в разделе SourceDisksNames INF-файла. |
|
SourcePathRoot — это полный путь к исходному файлу. Игнорируйте относительный источник, указанный в разделе SourceDisksNames INF-файла для исходного носителя, на котором находится файл. Этот флаг игнорируется, если указан SP_COPY_SOURCE_ABSOLUTE. |
|
Если целевой объект существует, ведет себя так, как если бы он использовался, и помещает файл в очередь для копирования при следующем перезапуске системы. |
|
Проверяет, существует ли целевой файл, и, если да, файл не перезаписывается. Вызывающий объект не получает уведомления. |
|
Проверяет каждый копируемый файл, чтобы узнать, указывают ли его ресурсы версии (или метки времени для файлов, не являющихся изображениями), что они не новее существующей копии на целевом объекте. Если копируемый файл не является более новым, файл не копируется. Вызывающий объект не получает уведомления. Функция возвращает значение FALSE, а GetLastError — NO_ERROR. |
[in] CopyMsgHandler
Необязательный указатель на функцию обратного вызова для уведомления о различных условиях, которые могут возникнуть во время операции копирования файла.
[in] Context
Необязательный указатель на определенное вызывающим значением, которое передается в качестве первого параметра функции обратного вызова.
Возвращаемое значение
Если функция выполнена успешно, возвращаемое значение будет ненулевым.
Если функция выполняется неудачно, возвращается нулевое значение. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.
Если GetLastError возвращает NO_ERROR, операция копирования файла не была завершена. Возможно, файл не был скопирован, так как операция копирования файла была ненужной или функция обратного вызова файла вернула значение FALSE.
Комментарии
Если в качестве целевого каталога установки файла указан UNC-каталог, необходимо убедиться, что он существует, прежде чем вызывать SetupInstallFile. Функции установки не проверка для существования и создания каталогов UNC. Если целевой каталог UNC не существует, установка файла завершится сбоем.
Примечание
Заголовок setupapi.h определяет SetupInstallFile в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора UNICODE. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows XP [только классические приложения] |
| Минимальная версия сервера | Windows Server 2003 [только классические приложения] |
| Целевая платформа | Windows |
| Header | setupapi.h |
| Библиотека | Setupapi.lib |
| DLL | Setupapi.dll |