Função SetupPromptForDiskA (setupapi.h)

Artigo
03/15/2023

[Essa função está disponível para uso nos sistemas operacionais indicados na seção Requisitos. Ele poderá ser alterado ou ficar indisponível em versões subsequentes. SetupAPI não deve mais ser usado para instalar aplicativos. Em vez disso, use o Windows Installer para desenvolver instaladores de aplicativos. SetupAPI continua a ser usado para instalar drivers de dispositivo.]

A função SetupPromptForDisk exibe uma caixa de diálogo que solicita um disco ao usuário.

Sintaxe

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

Manipule para a janela pai desta caixa de diálogo.

[in] DialogTitle

Ponteiro opcional para uma cadeia de caracteres terminada em nulo especificando o título da caixa de diálogo. Se esse parâmetro for NULL, o padrão de "%s--Files Needed"" (localizado) será usado. O "%s" é substituído pelo texto recuperado da janela pai. Se nenhum texto for recuperado da janela pai, o título será "Arquivos Necessários".

[in] DiskName

Ponteiro opcional para uma cadeia de caracteres terminada em nulo especificando o nome do disco a ser inserido. Se esse parâmetro for NULL, o padrão "(Desconhecido)" (localizado) será usado.

[in] PathToSource

Ponteiro opcional para uma cadeia de caracteres terminada em nulo especificando a parte do caminho do local esperado do arquivo, por exemplo, F:\x86. Se não for especificado, o caminho em que SetupPromptForDisk mais recentemente localizou um arquivo é usado. Se essa lista estiver vazia, um padrão do sistema será usado.

[in] FileSought

Ponteiro para uma cadeia de caracteres terminada em nulo especificando o nome do arquivo necessário (somente parte de nome de arquivo). O nome do arquivo será exibido se o usuário clicar no botão Procurar . Essa rotina procura o arquivo usando seus nomes de formulário compactados; Portanto, você pode passar cmd.exe e não se preocupar que o arquivo realmente exista como cmd.ex_ na mídia de origem.

[in] TagFile

Ponteiro opcional para uma cadeia de caracteres terminada em nulo especificando um arquivo de marca (somente parte de nome de arquivo) que identifica a presença de um volume de mídia removível específico. Se o caminho atualmente selecionado colocar o arquivo na mídia removível e um arquivo de marca for especificado, SetupPromptForDisk procurará o arquivo de marca na raiz da unidade para determinar se deseja continuar.

Por exemplo, se PathToSource for A:\x86, o tagfile for disk1.tag e o usuário digitar B:\x86 no controle de edição da caixa de diálogo de prompt, a rotina procurará B:\disk1.tag para determinar se deve continuar. Se o arquivo de marca não for encontrado, a função procurará o tagfile usando PathToSource.

Se um arquivo de marca não for especificado, a mídia removível funcionará como mídia não removível e FileSought será procurado antes de continuar.

[in] DiskPromptStyle

Especifica o comportamento da caixa de diálogo. Esse parâmetro pode ser uma combinação dos sinalizadores a seguir.

IDF_CHECKFIRST

Verifique o arquivo/disco antes de exibir a caixa de diálogo do prompt e, se houver, retorne DPROMPT_SUCCESS imediatamente.

IDF_NOBEEP

Impedir que a caixa de diálogo apita para chamar a atenção do usuário quando ela for exibida pela primeira vez.

IDF_NOBROWSE

Não exiba a opção procurar.

IDF_NOCOMPRESSED

Não marcar para versões compactadas do arquivo de origem.

IDF_NODETAILS

Não exiba informações detalhadas.

IDF_NOFOREGROUND

Impedir que a caixa de diálogo se torne a janela em primeiro plano.

IDF_NOSKIP

Não exiba a opção ignorar.

IDF_OEMDISK

Solicitar um disco fornecido por um fabricante de hardware.

IDF_WARNIFSKIP

Avisar o usuário de que ignorar um arquivo pode afetar a instalação.

[in, out] PathBuffer

Ponteiro opcional para um buffer que, após o retorno, recebe o caminho (sem nome de arquivo) do local especificado pelo usuário por meio da caixa de diálogo. Você deve usar uma cadeia de caracteres terminada em nulo. A cadeia de caracteres terminada em nulo não deve exceder o tamanho do buffer de destino. Você pode chamar a função uma vez para obter o tamanho do buffer necessário, alocar a memória necessária e, em seguida, chamar a função uma segunda vez para recuperar os dados. Usando essa técnica, você pode evitar erros devido a um tamanho de buffer insuficiente. Consulte a seção Comentários.

[in] PathBufferSize

Tamanho do buffer apontado por PathBuffer, em caracteres. Deve ser pelo menos MAX_PATH longo. Isso inclui o terminador nulo .

[in, out] PathRequiredSize

Ponteiro opcional para uma variável que recebe o tamanho necessário para PathBuffer, em caracteres. Isso inclui o terminador nulo .

Retornar valor

A função retorna um dos valores a seguir.

Para obter informações de erro estendidas, chame GetLastError.

Comentários

Se essa função for chamada com um PathBuffer de NULL e um PathBufferSize igual a zero, a função colocará o tamanho do buffer necessário para manter os dados especificados na variável apontada por PathRequiredSize. Se a função tiver êxito nisso, o valor retornado será NO_ERROR. Caso contrário, o valor retornado será um dos valores descritos na seção Valores retornados.

Observação

O cabeçalho setupapi.h define SetupPromptForDisk como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	setupapi.h
Biblioteca	Setupapi.lib
DLL	Setupapi.dll