Función SetupInstallFileExA (setupapi.h)
[Esta función está disponible para su uso en los sistemas operativos indicados en la sección Requisitos. En versiones posteriores podría modificarse o no estar disponible. SetupAPI ya no debe usarse para instalar aplicaciones. En su lugar, use Windows Installer para desarrollar instaladores de aplicaciones. SetupAPI sigue utilizándose para instalar controladores de dispositivo.
La función SetupInstallFileEx instala un archivo tal y como especifica un INFCONTEXT devuelto por SetupFindXXXLine o explícitamente por el nombre de archivo y la información de ruta de acceso. Esta función es la misma que SetupInstallFile, excepto que se devuelve un BOOL que indica si el archivo estaba en uso.
Si se copia un archivo, se requiere que el autor de la llamada de esta función tenga privilegios para escribir en el directorio de destino.
Sintaxis
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
);
Parámetros
[in] InfHandle
Puntero opcional al identificador de un archivo INF que contiene las secciones SourceDisksNames y SourceDisksFiles. Si existen secciones específicas de la plataforma para el sistema del usuario (por ejemplo, SourceDisksNames.x86 y SourceDisksFiles.x86), se usa la sección específica de la plataforma. Si no se especifica InfContext y CopyStyle incluye SP_COPY_SOURCE_ABSOLUTE o SP_COPY_SOURCEPATH_ABSOLUTE, se omite InfHandle .
[in] InfContext
Puntero opcional al contexto de una línea en una sección Copiar archivos de un archivo INF. La rutina busca este archivo en la sección SourceDisksFiles de InfHandle para obtener información de copia de archivos. Si no se especifica InfContext , SourceFile debe ser.
[in] SourceFile
Puntero opcional al nombre de archivo (sin ruta de acceso) del archivo que se va a copiar. El archivo se busca en la sección SourceDisksFiles. El parámetro SourceFile debe especificarse si InfContext no lo es. Sin embargo, SourceFile se omite si se especifica InfContext .
[in] SourcePathRoot
Puntero opcional a la ruta de acceso raíz del archivo que se va a copiar (por ejemplo, A:\ o F:). Las rutas de acceso de la sección SourceDisksNames se anexan a esta ruta de acceso. El parámetro SourcePathRoot se omite si CopyStyle incluye la marca SP_COPY_SOURCE_ABSOLUTE.
[in] DestinationName
Puntero opcional a un nuevo nombre para el archivo copiado. Si se especifica InfContext , DestinationName solo proporciona el nombre de archivo (sin ruta de acceso) del archivo de destino. Este parámetro puede ser NULL para indicar que el archivo de destino debe tener el mismo nombre que el archivo de origen. Si no se especifica InfContext , DestinationName proporciona la ruta de acceso de destino completa y el nombre de archivo para el destino.
[in] CopyStyle
Marcas que controlan el comportamiento de la operación de copia de archivos.
Estas marcas pueden ser una combinación de los valores siguientes.
| Valor | Significado |
|---|---|
|
Elimine el archivo de origen tras una copia correcta. El autor de la llamada no recibe una notificación si se produce un error en la eliminación. |
|
Copie el archivo solo si lo hace sobrescribe un archivo en la ruta de acceso de destino. |
|
Examine cada archivo que se va a copiar para ver si sus recursos de versión indican que es la misma versión o no más reciente que una copia existente en el destino.
La información de versión del archivo utilizada durante las comprobaciones de versión es que se especifica en los miembros dwFileVersionMS y dwFileVersionLS de una estructura de VS_FIXEDFILEINFO , tal como se rellenan en las funciones de versión. Si uno de los archivos no tiene recursos de versión o si tienen información de versión idéntica, el archivo de origen se considera más reciente. Si el archivo de origen no es más reciente o igual en la versión y se especifica CopyMsgHandler , se notifica al autor de la llamada y se puede cancelar la copia. Si no se especifica CopyMsgHandler , el archivo no se copia. |
|
Examine cada archivo que se va a copiar para ver si sus recursos de versión indican que no es más reciente que una copia existente en el destino. Si el archivo de origen es más reciente pero no es igual a la versión del destino existente, se copia el archivo. |
|
Compruebe si el archivo de destino existe y, si es así, notifique al autor de la llamada que pueda vetar la copia. Si no se especifica CopyMsgHandler , el archivo no se sobrescribe. |
|
No descomprima el archivo. Cuando se establece esta marca, el archivo de destino no recibe la forma sin comprimir del nombre de origen (si procede). Por ejemplo, copiar "f:\x86\cmd.ex_" en "\\install\temp" da como resultado un archivo de destino de "\\install\temp\cmd.ex_". Si no se especificó la marca SP_COPY_NODECOMP, el archivo se descomprimiría y el destino se llamaría "\\install\temp\cmd.exe". La parte de nombre de archivo de DestinationName, si se especifica, se quita y reemplaza por el nombre de archivo de origen. Cuando se especifica SP_COPY_NODECOMP, no se puede comprobar ninguna información de idioma o versión. |
|
Examine cada archivo que se va a copiar para ver si su idioma difiere del idioma de cualquier archivo existente que ya esté en el destino. Si es así, y se especifica CopyMsgHandler , se notifica al autor de la llamada y se puede cancelar la copia. Si no se especifica CopyMsgHandler , el archivo no se copia. |
|
SourceFile es una ruta de acceso de origen completa. No lo busque en la sección SourceDisksNames del archivo INF. |
|
SourcePathRoot es la parte de ruta de acceso completa del archivo de origen. Omita el origen relativo especificado en la sección SourceDisksNames del archivo INF del medio de origen donde se encuentra el archivo. Esta marca se omite si se especifica SP_COPY_SOURCE_ABSOLUTE. |
|
Si el destino existe, comporte como si estuviera en uso y poner en cola el archivo para copiar en el siguiente reinicio del sistema. |
|
Si el archivo estaba en uso durante la operación de copia, avise al usuario de que el sistema requiere un reinicio. |
|
No proporcione al usuario la opción de omitir un archivo. |
|
Compruebe si el archivo de destino existe y, si es así, el archivo no se sobrescribe. No se notifica al autor de la llamada. |
|
Examine cada archivo que se va a copiar para ver si sus recursos de versión (o marcas de tiempo para archivos que no son de imagen) indican que no es más reciente que una copia existente en el destino. Si el archivo que se copia no es más reciente, el archivo no se copia. No se notifica al autor de la llamada. |
|
Si el usuario intenta omitir un archivo, avisa de que omitir un archivo puede afectar a la instalación. (Se usa para archivos críticos del sistema). |
[in] CopyMsgHandler
Puntero opcional a una función de devolución de llamada para recibir una notificación de varias condiciones que pueden surgir durante la copia del archivo.
[in] Context
Puntero a un valor definido por el autor de la llamada que se pasa como primer parámetro de la función de devolución de llamada.
[out] FileWasInUse
Puntero a una variable en la que esta función devuelve una marca que indica si el archivo estaba en uso. Este parámetro es obligatorio.
Valor devuelto
Si la función se ejecuta correctamente, el valor devuelto es un valor distinto de cero.
Si la función no se realiza correctamente, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError.
Si GetLastError devuelve NO_ERROR, no se completó la operación de copia de archivos. Es posible que el archivo no se haya copiado porque la operación de copia de archivos no era necesaria o porque la función de devolución de llamada de archivo devolvió FALSE.
Comentarios
Esta API se usa normalmente al instalar nuevas versiones de archivos del sistema que probablemente estén en uso. Actualiza un valor BOOL que indica si el archivo estaba en uso. Si el archivo estaba en uso, la operación de copia de archivos se pospone hasta que se reinicie el sistema.
Si se especifica un directorio UNC como directorio de destino de una instalación de archivos, debe asegurarse de que existe antes de llamar a SetupInstallFileEx. Las funciones de instalación no comprueban la existencia de y no crean directorios UNC. Si el directorio UNC de destino no existe, se produce un error en la instalación del archivo.
Nota
El encabezado setupapi.h define SetupInstallFileEx como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutro de codificación con código que no es neutral de codificación puede provocar discrepancias que dan lugar a errores de compilación o en tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.
Requisitos
| Requisito | Value |
|---|---|
| Cliente mínimo compatible | Windows XP [solo aplicaciones de escritorio] |
| Servidor mínimo compatible | Windows Server 2003 [solo aplicaciones de escritorio] |
| Plataforma de destino | Windows |
| Encabezado | setupapi.h |
| Library | Setupapi.lib |
| Archivo DLL | Setupapi.dll |
Vea también
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de