15.2.2 Initializing the Application

To initialize a Control Panel application, Control Panel sends the CPL_INIT message first to the CPlApplet function, which prompts the application DLL to perform initialization procedures. If initialization succeeds, CPlApplet returns nonzero.

If CPlApplet returns zero in response to the CPL_INIT message, Control Panel calls the FreeLibrary function and ends communication with the application DLL. This is the only way an application can notify Control Panel of initialization problems and prevent the application from being loaded.

If initialization is successful, Control Panel sends the CPL_GETCOUNT message. The CPlApplet function responds by returning the number of applications serviced by the application DLL. This number determines how many icons Control Panel displays for the DLL.

Once Control Panel finds out the number of applications serviced by the DLL, it sends the CPL_NEWINQUIRE message once for each application. The lParam1 parameter specifies the application number, which is zero for the first application and CPL_GETCOUNT minus 1 for the last application.

Control Panel passes a far pointer to a NEWCPLINFO structure in the lParam2 parameter. The NEWCPLINFO structure has the following form:

typedef struct tagNEWCPLINFO /* ncpli */
{
    DWORD dwSize;          /* length of structure, in bytes     */
    DWORD dwFlags;         /* setup flags                       */
    DWORD dwHelpContext;   /* help-context number               */
    LONG  lData;           /* application-defined data          */
    HICON hIcon;           /* handle of icon (owned by CPL.EXE) */
    char  szName[32];      /* short-name string                 */
    char  szInfo[64];      /* description string (status line)  */
    char  szHelpFile[128]; /* path to help file                 */
} NEWCPLINFO;

The CPlApplet function must fill in the NEWCPLINFO structure. The function must assign values for the dwSize, hIcon, szName, and szInfo members for the structure size, application icon, short name, and description. To add an accelerator key for the application, precede the selected accelerator character in the szName string with an ampersand. If the application DLL supports context-sensitive Help, the CPlApplet function should also assign the values for the dwHelpContext and szHelpFile members. The lData member can be used for application-defined data.

Note:

The CPL_NEWINQUIRE message and NEWCPLINFO structure replace the CPL_INQUIRE message and CPLINFO structure. The latter have been kept for backward compatibility with Windows version 3.0. If the application DLL does not respond to the CPL_NEWINQUIRE message, Control Panel sends it the CPL_INQUIRE message. Then the lParam2 parameter points to a CPLINFO structure rather than to a NEWCPLINFO structure. For more information about these structures, see the Microsoft Windows Programmer's Reference, Volume 3.