Edit

CPL_INQUIRE message

  • Article

Sent to the CPlApplet function of a Control Panel application to request information about a dialog box that the application supports.

Parameters

uAppNum

The dialog box number. This number must be in the range zero through one less than the value returned in response to the CPL_GETCOUNT message (CPL_GETCOUNT – 1).

lpcpli

The address of a CPLINFO structure. The application must fill this structure with resource identifiers for the icon, short name, description, and any user-defined value associated with the dialog box.

Return value

If the CPlApplet function processes this message successfully, it should return zero.

Remarks

The Control Panel sends the CPL_INQUIRE message once for each dialog box supported by your application. The Control Panel also sends a CPL_NEWINQUIRE message for each dialog box. These messages are sent immediately after the CPL_GETCOUNT message. However, the system does not guarantee the order in which the CPL_INQUIRE and CPL_NEWINQUIRE messages are sent.

You can perform initialization for the dialog box when you receive CPL_INQUIRE. If you must allocate memory, do so in response to the CPL_INIT message.

The CPL_NEWINQUIRE message returns information in a form that the system cannot cache. For this reason, most CPlApplet functions should process CPL_INQUIRE and ignore CPL_NEWINQUIRE.

The only applications that should use CPL_NEWINQUIRE are those that need to change their icon or display strings based on the state of the computer. In this case, your CPL_INQUIRE handler should specify the CPL_DYNAMIC_RES value for the idIcon, idName, or idInfo members of the CPLINFO structure, rather than specifying a valid resource identifier. This causes the Control Panel to send the CPL_NEWINQUIRE message each time it needs the icon and display strings, allowing you to specify information based on the current state of the computer. This is significantly slower than using cached information.

Requirements

Requirement Value
Minimum supported client
 Windows XP [desktop apps only]
Minimum supported server
 Windows 2000 Server [desktop apps only]
Header
Cpl.h