Função SetupCopyErrorA (setupapi.h)

Artigo
08/26/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 SetupCopyError gera uma caixa de diálogo para notificar um usuário sobre um erro de arquivo de cópia.

Sintaxe

WINSETUPAPI UINT SetupCopyErrorA(
  [in]      HWND   hwndParent,
  [in]      PCSTR  DialogTitle,
  [in]      PCSTR  DiskName,
  [in]      PCSTR  PathToSource,
  [in]      PCSTR  SourceFile,
  [in]      PCSTR  TargetPathFile,
  [out]     UINT   Win32ErrorCode,
  [in]      DWORD  Style,
  [in, out] PSTR   PathBuffer,
  [in]      DWORD  PathBufferSize,
  [in, out] PDWORD PathRequiredSize
);

Parâmetros

[in] hwndParent

O identificador para a janela pai dessa caixa de diálogo.

[in] DialogTitle

Um ponteiro opcional para uma cadeia de caracteres terminada em nulo que especifica o título da caixa de diálogo.

Este parâmetro pode ser NULL. Se esse parâmetro for NULL, o título padrão de "Erro de Cópia" (localizado no idioma do sistema) será usado.

[in] DiskName

Um ponteiro opcional para uma cadeia de caracteres terminada em nulo que especifica o nome do disco a ser inserido.

Este parâmetro pode ser NULL. Se esse parâmetro for NULL, o nome padrão "(Desconhecido)" (localizado no idioma do sistema) será usado.

[in] PathToSource

Um ponteiro para o componente de caminho do arquivo de origem em que uma operação falha, por exemplo, F:\x86.

Use uma cadeia de caracteres terminada em nulo.

[in] SourceFile

Um ponteiro para uma cadeia de caracteres terminada em nulo que especifica a parte filename do arquivo em que uma operação falha.

Use uma cadeia de caracteres terminada em nulo. Esse nome de arquivo será exibido se o usuário clicar nos botões Detalhes ou Procurar . A função SetupCopyError procura o arquivo que usa 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] TargetPathFile

Um ponteiro opcional para uma cadeia de caracteres terminada em nulo que especifica o caminho completo do arquivo de destino para operações de renomeação e cópia.

Use uma cadeia de caracteres terminada em nulo. Este parâmetro pode ser NULL. Se TargetPathFile não for especificado, "(Desconhecido)" (localizado no idioma do sistema) será usado.

[out] Win32ErrorCode

Se ocorrer um erro, esse membro será o Código de Erro do Sistema.

Se um erro não ocorrer, ele será NO_ERROR.

[in] Style

Os sinalizadores que controlam exibem a formatação e o comportamento de uma caixa de diálogo.

Esse parâmetro pode ser um dos sinalizadores a seguir.

IDF_NOBROWSE

Não exiba a opção procurar.

IDF_NOSKIP

Não exiba a opção ignorar arquivo.

IDF_NODETAILS

Não exiba a opção de detalhes.

Se esse sinalizador for definido, os parâmetros TargetPathFile e Win32ErrorCode poderão ser omitidos.

IDF_NOCOMPRESSED

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

IDF_OEMDISK

A origem da operação é um disco que um fabricante de hardware fornece.

IDF_NOBEEP

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

IDF_NOFOREGROUND

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

IDF_WARNIFSKIP

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

[in, out] PathBuffer

Um ponteiro opcional para uma variável na qual essa função retorna o caminho (não incluindo o nome do arquivo) do local especificado por um usuário na 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. Para evitar erros de buffer insuficientes, PathBuffer deve ser pelo menos MAX_PATH. Para obter mais informações, confira a seção Comentários deste tópico.

[in] PathBufferSize

O tamanho do buffer para o qual PathBuffer aponta, em caracteres.

O tamanho do buffer deve ser pelo menos MAX_PATH caracteres, incluindo o terminador nulo .

[in, out] PathRequiredSize

Um ponteiro opcional para uma variável na qual essa função retorna o tamanho do buffer necessário, em caracteres, incluindo 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 de 0 (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 for bem-sucedida, o valor retornado será NO_ERROR. Caso contrário, o valor retornado será um dos valores especificados.

Para evitar erros de buffer insuficientes, ReturnBuffer deve ser pelo menos MAX_PATH.

Observação

O cabeçalho setupapi.h define SetupCopyError 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