Método IWiaDevMgr::GetImageDlg (wia_xp.h)

O método IWiaDevMgr::GetImageDlg exibe uma ou mais caixas de diálogo que permitem que um usuário adquira uma imagem de um dispositivo WIA (Aquisição de Imagens do Windows) e escreva a imagem em um arquivo especificado. Esse método combina a funcionalidade de IWiaDevMgr::SelectDeviceDlg para encapsular completamente a aquisição de imagens em uma única chamada à API.

Sintaxe

HRESULT GetImageDlg(
  [in]      HWND     hwndParent,
  [in]      LONG     lDeviceType,
  [in]      LONG     lFlags,
  [in]      LONG     lIntent,
  [in]      IWiaItem *pItemRoot,
  [in]      BSTR     bstrFilename,
  [in, out] GUID     *pguidFormat
);

Parâmetros

[in] hwndParent

Digite: HWND

Identificador da janela que possui a caixa de diálogo Obter Imagem .

[in] lDeviceType

Tipo: LONG

Especifica qual tipo de dispositivo WIA usar. É definido como StiDeviceTypeDefault, StiDeviceTypeScanner ou StiDeviceTypeDigitalCamera.

[in] lFlags

Tipo: LONG

Especifica o comportamento da caixa de diálogo. Pode ser definido com os seguintes valores:

Sinalizador	Significado
0	Comportamento padrão.
WIA_SELECT_DEVICE_NODEFAULT	Force esse método a exibir a caixa de diálogo Selecionar Dispositivo . Para obter mais informações, consulte a seção Comentários desta página de referência.
WIA_DEVICE_DIALOG_SINGLE_IMAGE	Restrinja a seleção de imagem a uma única imagem na caixa de diálogo de aquisição de imagem do dispositivo.
WIA_DEVICE_DIALOG_USE_COMMON_UI	Use a interface do usuário do sistema, se disponível, em vez da interface do usuário fornecida pelo fornecedor. Se a interface do usuário do sistema não estiver disponível, a interface do usuário do fornecedor será usada. Se nenhuma interface do usuário estiver disponível, a função retornará E_NOTIMPL.

[in] lIntent

Tipo: LONG

Especifica que tipo de dados a imagem deve representar. Para obter uma lista de valores de intenção de imagem, consulte Constantes de intenção de imagem.

[in] pItemRoot

Tipo: IWiaItem*

Ponteiro para a interface da árvore hierárquica de objetos IWiaItem retornados por IWiaDevMgr::CreateDevice.

[in] bstrFilename

Tipo: BSTR

Especifica o nome do arquivo no qual os dados da imagem são gravados.

[in, out] pguidFormat

Tipo: GUID*

Na entrada, contém um ponteiro para um GUID que especifica o formato a ser usado. Na saída, mantém o formato usado. Passe IID_NULL para usar o formato padrão.

Retornar valor

Tipo: HRESULT

IWiaDevMgr::GetImageDlg retornará S_FALSE se o usuário cancelar as caixas de diálogo de seleção ou aquisição de imagem do dispositivo, WIA_S_NO_DEVICE_AVAILABLE se nenhum dispositivo WIA estiver disponível no momento, E_NOTIMPL se nenhuma interface do usuário estiver disponível e S_OK se os dados forem transferidos com êxito.

IWiaDevMgr::GetImageDlg retorna um valor especificado em Códigos de Erro ou um erro COM padrão se falhar por qualquer motivo diferente daqueles especificados.

Comentários

Invocar esse método exibe uma caixa de diálogo que permite que os usuários adquiram imagens. Ele também pode exibir a caixa de diálogo Selecionar Dispositivo criada pelo método IWiaDevMgr::SelectDeviceDlg .

Se o aplicativo passar NULL para o valor do parâmetro pItemRoot , IWiaDevMgr::GetImageDlg exibirá a caixa de diálogo Selecionar Dispositivo que permite que o usuário selecione o dispositivo de entrada WIA. Se o aplicativo especificar um dispositivo de entrada WIA passando um ponteiro para a árvore de itens do dispositivo por meio do parâmetro pItemRoot , IWiaDevMgr::GetImageDlg não exibirá a caixa de diálogo Selecionar Dispositivo . Em vez disso, ele usará o dispositivo de entrada especificado para adquirir a imagem.

Ao usar a caixa de diálogo Selecionar Dispositivo , os aplicativos podem especificar tipos de dispositivos de entrada WIA. Para fazer isso, eles devem definir o parâmetro pItemRoot como NULL e passar as constantes apropriadas por meio do parâmetro lDeviceType . Se mais de um dispositivo do tipo especificado estiver presente, o IWiaDevMgr::GetImageDlg exibirá a caixa de diálogo Selecionar Dispositivo para permitir que o usuário selecione qual dispositivo será usado.

Se IWiaDevMgr::GetImageDlg encontrar apenas um dispositivo correspondente, ele não exibirá a caixa de diálogo Selecionar Dispositivo . Em vez disso, ele selecionará o dispositivo correspondente. Você pode substituir esse comportamento e forçar IWiaDevMgr::GetImageDlg a exibir a caixa de diálogo Selecionar Dispositivo passando WIA_SELECT_DEVICE_NODEFAULT como o valor do parâmetro lFlags .

É recomendável que os aplicativos disponibilizem a seleção de dispositivo e imagem por meio de um item de menu chamado De scanner ou câmera no menu Arquivo .

A caixa de diálogo deve ter direitos suficientes para a pasta para bstrFilename que possa salvar o arquivo com um nome de arquivo exclusivo. A pasta também deve ser protegida com uma ACL (lista de controle de acesso) porque contém dados do usuário.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000 Professional, 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	wia_xp.h (inclua Wia.h)
Biblioteca	Wiaguid.lib
DLL	Wiaservc.dll