Compartilhar via


Manipulando mensagens do Windows para páginas de propriedades

Quando um provedor de página de propriedades do dispositivo manipula uma solicitação para criar uma página de propriedades para seu dispositivo ou classe de dispositivo, ele retorna o endereço de um procedimento de caixa de diálogo para a página de propriedades. O procedimento da caixa de diálogo deve inicializar a página de propriedades quando receber uma mensagem de WM_INITDIALOG e deve estar preparado para lidar com alterações nas propriedades do dispositivo quando receber uma mensagem de WM_NOTIFY. O procedimento também pode lidar com qualquer outra mensagem que possa exigir, conforme descrito na documentação do SDK do Microsoft Windows.

Em resposta a uma mensagem de WM_INITDIALOG, o procedimento da caixa de diálogo inicializa informações na página de propriedades. Essas informações podem incluir um ícone que representa o dispositivo, o nome amigável do dispositivo e sua descrição do dispositivo PnP.

SetupDiLoadClassIcon carrega os ícones de uma classe de dispositivo especificada e retorna um identificador para o ícone grande carregado que pode ser usado em uma chamada subsequente para SendDlgItemMessage. Por exemplo:

if (SetupDiLoadClassIcon(
        &pTestPropPageData->DeviceInfoData->ClassGuid, &ClassIcon, 
        NULL)) {
    OldIcon = (HICON)SendDlgItemMessage(
                        hDlg, 
                        IDC_TEST_ICON,
                        STM_SETICON, (WPARAM)ClassIcon, 0);
    if (OldIcon) {
                DestroyIcon(OldIcon);
    }
}

O identificador retornado em ClassIcon pode ser convertido no WPARAM exigido pela função SendDlgItemMessage. No exemplo, IDC_TEST_ICON identifica o controle na caixa de diálogo que recebe a mensagem STM_SETICON. O valor de IDC_TEST_ICON deve ser definido no provedor. Para funções adicionais que manipulam ícones e bitmaps, consulte Funções de instalação do dispositivo. Para obter mais informações sobre SendDlgItemMessage, DestroyIcon e usando ícones em caixas de diálogo, consulte a documentação do SDK do Windows.

Além de um ícone que representa o dispositivo, uma página de propriedades típica do dispositivo inclui uma descrição ou um "nome amigável" do dispositivo e mostra as configurações atuais das propriedades do dispositivo. O gerenciador de Plug and Play (PnP) armazena as propriedades PnP de cada dispositivo no registro. Um provedor de página de propriedades pode chamar SetupDiGetDeviceRegistryProperty para obter o valor de qualquer propriedade desse tipo. Se as informações de configuração específicas do dispositivo ou da classe também tiverem sido armazenadas no registro como parte do processo de instalação, um provedor de página de propriedades poderá usar outras funções SetupDiXxx para extrair essas informações para exibição. Para obter mais informações, consulte Funções de instalação de dispositivo.

Quando determinados tipos de alterações ocorrem na página, a folha de propriedades envia uma mensagem WM_NOTIFY para o procedimento da caixa de diálogo. O procedimento da caixa de diálogo deve ser preparado para extrair o código de notificação dos parâmetros da mensagem e responder adequadamente.

Para obter mais informações sobre as notificações que um procedimento de caixa de diálogo pode encontrar, como as notificações de PSN_APPLY ou PSN_HELP e como o procedimento deve tratá-las, consulte Notificações na documentação do SDK do Windows.

Notificações do PSN_APPLY

A folha de propriedades envia uma mensagem de notificação PSN_APPLY quando o usuário clica em OK, Fechar ou Aplicar. Em resposta a essa mensagem, o procedimento da caixa de diálogo deve validar e aplicar as alterações feitas pelo usuário.

Quando ele recebe a notificação de PSN_APPLY, o provedor deve fazer o seguinte:

  1. Se ainda não tiver feito isso, obtenha um ponteiro para os parâmetros de instalação do dispositivo (estrutura SP_DEVINSTALL_PARAMS ) para o dispositivo. Essa estrutura está disponível chamando SetupDiGetDeviceInstallParams, passando os DeviceInfoSet e DeviceInfoData salvos que foram passados na área referenciada pelo membro lParam da estrutura PROPSHEETPAGE.

  2. Verifique se as alterações do usuário são válidas.

  3. Se o provedor permitir que um usuário defina uma propriedade que exija que o Windows remova e reinicie o dispositivo, o provedor deverá definir o sinalizador DI_FLAGSEX_PROPCHANGE_PENDING no campo FlagsEx da estrutura de SP_DEVINSTALL_PARAMS retornada.

    No entanto, se o provedor puder garantir que as alterações não exijam que os drivers do dispositivo sejam interrompidos e reiniciados, ele não precisará definir esse sinalizador.

  4. Chame SetupDiSetDeviceInstallParams com a estrutura SP_DEVINSTALL_PARAMS alterada para definir os novos parâmetros.

Notificações do PSN_RESET

A folha de propriedades envia uma mensagem de notificação PSN_RESET quando o usuário clica em Cancelar. Em resposta a essa mensagem, o procedimento da caixa de diálogo deve descartar as alterações feitas pelo usuário.