Criando páginas de propriedades personalizadas

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, o provedor deve seguir as seguintes etapas:

1. Chame SetupDiGetClassInstallParams para obter os parâmetros de instalação da classe atual para o dispositivo. Por exemplo:

   SP_ADDPROPERTYPAGE_DATA AddPropertyPageData;
   :
   ZeroMemory(&AddPropertyPageData, sizeof(SP_ADDPROPERTYPAGE_DATA));
   AddPropertyPageData.ClassInstallHeader.cbSize = sizeof(SP_CLASSINSTALL_HEADER);
   
   if (SetupDiGetClassInstallParams(DeviceInfoSet, DeviceInfoData,
        (PSP_CLASSINSTALL_HEADER)&AddPropertyPageData,
        sizeof(SP_ADDPROPERTYPAGE_DATA), NULL )) {
   ...
   

   Neste exemplo, o código inicializa zero a estrutura na qual os parâmetros de instalação do dispositivo serão retornados e define o tamanho do cabeçalho de instalação da classe no campo cbSize conforme exigido por SetupDiGetClassInstallParams. O cabeçalho de instalação de classe é o primeiro membro de cada estrutura de parâmetros de instalação de classe.

2. Verifique se o número máximo de páginas dinâmicas do dispositivo ainda não foi atendido usando uma instrução como a seguinte:

   if (AddPropertyPageData.NumDynamicPages < 
       MAX_INSTALLWIZARD_DYNAPAGES)
    ...
   

   Se o teste falhar, não inicialize nem crie a página. Em vez disso, retorne NO_ERROR.

3. Aloque memória na qual salvar todos os dados específicos do dispositivo que serão necessários posteriormente no procedimento da caixa de diálogo e inicialize essa memória com os dados. O provedor deve liberar essa memória em seu retorno de chamada da página de propriedades quando a página de propriedades for destruída.

   Para provedores que são co-instaladores, esses dados específicos do dispositivo devem incluir o DeviceInfoSet e o DeviceInfoData passados com o código dif (função de instalação de dispositivo ) DIF_ADDPROPERTYPAGE_ADVANCED .

   Por exemplo, um provedor de página de propriedades pode definir e usar uma estrutura, conforme mostrado no exemplo a seguir:

   typedef struct _TEST_PROP_PAGE_DATA {
       HDEVINFO DeviceInfoSet;
       PSP_DEVINFO_DATA DeviceInfoData;
   } TEST_PROP_PAGE_DATA, *PTEST_PROP_PAGE_DATA;
   ...
   PTEST_PROP_PAGE_DATA     pMyPropPageData;
   ...
   pMyPropPageData = HeapAlloc(GetProcessHeap(), 0, sizeof(TESTPROP_PAGE_DATA));
   

4. Inicialize uma estrutura PROPSHEETPAGE com informações sobre a página de propriedades personalizadas:

   • Em dwFlags, defina o sinalizador PSP_USECALLBACK e quaisquer outros sinalizadores necessários para a página de propriedades personalizadas. O sinalizador PSP_USECALLBACK indica que uma função de retorno de chamada foi fornecida.
   • Em pfnCallback, defina um ponteiro para a função de retorno de chamada para a página de propriedades. No retorno de chamada, processe a mensagem PSPCB_RELEASE e libere a memória alocada na etapa 3.
   • Em pfnDlgProc, defina um ponteiro para o procedimento da caixa de diálogo da página de propriedades.
   • Em lParam, passe um ponteiro para a área de memória que foi alocada e inicializada na etapa 3.
   • Defina outros membros conforme apropriado para a página de propriedades personalizadas. Consulte a documentação SDK do Microsoft Windows para obter mais informações sobre a estrutura PROPSHEETPAGE.

5. Chame CreatePropertySheetPage para criar a nova página.

6. Adicione a nova página à lista de páginas de propriedades dinâmicas no membro DynamicPages dos parâmetros de instalação da classe e incremente o membro NumDynamicPages .

7. Repita as etapas de 2 a 6 para cada página de propriedade personalizada adicional.

8. Chame SetupDiSetClassInstallParams para definir os novos parâmetros de instalação de classe, que incluem a estrutura da página de propriedades atualizada.

9. Retornar NO_ERROR.

O Windows adiciona as páginas de propriedades recém-criadas à folha de propriedades do dispositivo e Gerenciador de Dispositivos faz chamadas à API do Microsoft Win32 para criar a planilha. Quando a página de propriedades é exibida, o sistema chama o procedimento da caixa de diálogo especificado na estrutura PROPSHEETPAGE.