Función SetupPromptForDiskA (setupapi.h)

Artículo
03/15/2023

[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 usándose para instalar controladores de dispositivos.

La función SetupPromptForDisk muestra un cuadro de diálogo que solicita al usuario un disco.

Sintaxis

WINSETUPAPI UINT SetupPromptForDiskA(
  [in]      HWND   hwndParent,
  [in]      PCSTR  DialogTitle,
  [in]      PCSTR  DiskName,
  [in]      PCSTR  PathToSource,
  [in]      PCSTR  FileSought,
  [in]      PCSTR  TagFile,
  [in]      DWORD  DiskPromptStyle,
  [in, out] PSTR   PathBuffer,
  [in]      DWORD  PathBufferSize,
  [in, out] PDWORD PathRequiredSize
);

Parámetros

[in] hwndParent

Identificador de la ventana primaria de este cuadro de diálogo.

[in] DialogTitle

Puntero opcional a una cadena terminada en null que especifica el título del cuadro de diálogo. Si este parámetro es NULL, se usa el valor predeterminado "%s--Files Needed"" (localizado). "%s" se reemplaza por el texto recuperado de la ventana primaria. Si no se recupera ningún texto de la ventana primaria, el título es "Archivos necesarios".

[in] DiskName

Puntero opcional a una cadena terminada en null que especifica el nombre del disco que se va a insertar. Si este parámetro es NULL, se usa el valor predeterminado "(Unknown)" (localizado).

[in] PathToSource

Puntero opcional a una cadena terminada en null que especifica la parte de ruta de acceso de la ubicación esperada del archivo, por ejemplo, F:\x86. Si no se especifica, se usa la ruta de acceso en la que SetupPromptForDisk ha localizado recientemente un archivo. Si esa lista está vacía, se usa un valor predeterminado del sistema.

[in] FileSought

Puntero a una cadena terminada en null que especifica el nombre del archivo necesario (solo parte de nombre de archivo). El nombre de archivo se muestra si el usuario hace clic en el botón Examinar . Esta rutina busca el archivo utilizando sus nombres de formulario comprimido; Por lo tanto, puede pasar cmd.exe y no preocuparse de que el archivo existe realmente como cmd.ex_ en el medio de origen.

[in] TagFile

Puntero opcional a una cadena terminada en null que especifica un archivo de etiqueta (solo parte de nombre de archivo) que identifica la presencia de un volumen multimedia extraíble determinado. Si la ruta de acceso seleccionada actualmente colocaría el archivo en medios extraíbles y se especifica un archivo de etiqueta, SetupPromptForDisk busca el archivo de etiqueta en la raíz de la unidad para determinar si desea continuar.

Por ejemplo, si PathToSource es A:\x86, el archivo de etiquetas es disk1.tag y el usuario escribe B:\x86 en el control de edición del cuadro de diálogo de solicitud, la rutina busca B:\disk1.tag para determinar si desea continuar. Si no se encuentra el archivo de etiqueta, la función busca el archivo de etiquetas mediante PathToSource.

Si no se especifica un archivo de etiqueta, los medios extraíbles funcionan igual que los medios no extraíbles y FileSought se buscan antes de continuar.

[in] DiskPromptStyle

Especifica el comportamiento del cuadro de diálogo. Este parámetro puede ser una combinación de las marcas siguientes.

IDF_CHECKFIRST

Compruebe el archivo o disco antes de mostrar el cuadro de diálogo de solicitud y, si está presente, devuelva DPROMPT_SUCCESS inmediatamente.

IDF_NOBEEP

Evite que el cuadro de diálogo se filte para que el usuario se preste atención cuando aparezca por primera vez.

IDF_NOBROWSE

No muestre la opción Examinar.

IDF_NOCOMPRESSED

No compruebe si hay versiones comprimidas del archivo de origen.

IDF_NODETAILS

No muestre información detallada.

IDF_NOFOREGROUND

Impedir que el cuadro de diálogo se convierta en la ventana de primer plano.

IDF_NOSKIP

No muestre la opción skip.

IDF_OEMDISK

Solicitar un disco proporcionado por un fabricante de hardware.

IDF_WARNIFSKIP

Advertir al usuario que omitir un archivo puede afectar a la instalación.

[in, out] PathBuffer

Puntero opcional a un búfer que, tras devolver, recibe la ruta de acceso (sin nombre de archivo) de la ubicación especificada por el usuario a través del cuadro de diálogo. Debe usar una cadena terminada en NULL. La cadena terminada en null no debe superar el tamaño del búfer de destino. Puede llamar a la función una vez para obtener el tamaño de búfer necesario, asignar la memoria necesaria y, a continuación, llamar a la función una segunda vez para recuperar los datos. Con esta técnica, puede evitar errores debido a un tamaño de búfer insuficiente. Consulte la sección Comentarios.

[in] PathBufferSize

Tamaño del búfer al que apunta PathBuffer, en caracteres. Debe ser al menos MAX_PATH largo. Esto incluye el terminador nulo .

[in, out] PathRequiredSize

Puntero opcional a una variable que recibe el tamaño necesario para PathBuffer, en caracteres. Esto incluye el terminador nulo .

Valor devuelto

La función devuelve uno de los valores siguientes.

Para obtener información de error extendida, llame a GetLastError.

Comentarios

Si se llama a esta función con pathBuffer de NULL y pathBufferSize de cero, la función coloca el tamaño del búfer necesario para contener los datos especificados en la variable a la que apunta PathRequiredSize. Si la función se realiza correctamente, el valor devuelto se NO_ERROR. De lo contrario, el valor devuelto es uno de los valores descritos en la sección Valores devueltos.

Nota

El encabezado setupapi.h define SetupPromptForDisk 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 neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o 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