Crear páginas de propiedades personalizadas

Cuando un proveedor de páginas de propiedades de dispositivo controla una solicitud para crear una página de propiedades para su dispositivo o clase de dispositivo, el proveedor debe seguir estos pasos:

1. Llame a SetupDiGetClassInstallParams para obtener los parámetros de instalación de clase actuales para el dispositivo. Por ejemplo:

   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 )) {
   ...
   

   En este ejemplo, el código inicializa la estructura en la que se devolverán los parámetros de instalación del dispositivo y establece el tamaño del encabezado de instalación de clase en el campo cbSize según lo requiera SetupDiGetClassInstallParams. El encabezado de instalación de clase es el primer miembro de cada estructura de parámetros de instalación de clase.

2. Asegúrese de que aún no se ha cumplido el número máximo de páginas dinámicas para el dispositivo mediante una instrucción como la siguiente:

   if (AddPropertyPageData.NumDynamicPages < 
       MAX_INSTALLWIZARD_DYNAPAGES)
    ...
   

   Si se produce un error en la prueba, no inicialice ni cree la página. En su lugar, devuelva NO_ERROR.

3. Asigne memoria en la que se guardarán los datos específicos del dispositivo que se necesitarán más adelante en el procedimiento del cuadro de diálogo e inicializar esta memoria con los datos. El proveedor debe liberar esta memoria en la devolución de llamada de la página de propiedades cuando se destruye la página de propiedades.

   En el caso de los proveedores que son coinstaladores, estos datos específicos del dispositivo deben incluir DeviceInfoSet y DeviceInfoData pasados con el código de la función de instalación de dispositivos (DIF) de DIF_ADDPROPERTYPAGE_ADVANCED.

   Por ejemplo, un proveedor de páginas de propiedades puede definir y usar una estructura como se muestra en el ejemplo siguiente:

   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. Inicialice una estructura PROPSHEETPAGE con información sobre la página de propiedades personalizada:

   • En dwFlags, establezca la marca PSP_USECALLBACK y cualquier otra marca necesaria para la página de propiedades personalizada. La marca PSP_USECALLBACK indica que se ha proporcionado una función de devolución de llamada.
   • En pfnCallback, establezca un puntero a la función de devolución de llamada de la página de propiedades. En la devolución de llamada, procese el mensaje PSPCB_RELEASE y libere la memoria que se asignó en el paso 3.
   • En pfnDlgProc, establezca un puntero al procedimiento del cuadro de diálogo para la página de propiedades.
   • En lParam, pase un puntero al área de memoria que se asignó e inicializó en el paso 3.
   • Establezca otros miembros según corresponda para la página de propiedades personalizada. Consulte la documentación de Microsoft Windows SDK para obtener más información sobre la estructura PROPSHEETPAGE.

5. Llame a CreatePropertySheetPage para crear la nueva página.

6. Agregue la nueva página a la lista de páginas de propiedades dinámicas en el miembro DynamicPages de los parámetros de instalación de clase e incremente el miembro NumDynamicPages .

7. Repita los pasos del 2 al 6 para cada página de propiedades personalizada adicional.

8. Llame a SetupDiSetClassInstallParams para establecer los nuevos parámetros de instalación de clase, que incluyen la estructura actualizada de la página de propiedades.

9. Devuelve NO_ERROR.

Windows agrega las páginas de propiedades recién creadas a la hoja de propiedades del dispositivo y Administrador de dispositivos realiza llamadas API de Microsoft Win32 para crear la hoja. Cuando se muestra la página de propiedades, el sistema llama al procedimiento de cuadro de diálogo especificado en la estructura PROPSHEETPAGE.