Writing the dialog procedure for a cred type panel

Once each credentials provider has had a chance to add a credentials type panel for the new credentials dialog, the application will attempt to create all the dialog panels. It will use the dialog template and the dialog procedure specified in the dlg_proc and dlg_template members of the khui_new_creds_by_type structure.

The credentials type panel will be an ordinary dialog that is created as a child of the new credentials window. Therefore, the dialog template should have the WS_CHILD style and the WS_EX_CONTROLPARENT extended style set so that the main dialog procedure can correctly navigate the child dialog.

Handling Messages

WM_INITDIALOG

When the application creates a credentials type panel dialog, it passes a pointer to the khui_new_creds structure as the LPARAM parameter. This can be used to query for the credentials type panel for the plug-in, as follows:

    // Handler for WM_INITDIALOG:
    // HWND hwnd, WPARAM wParam and LPARAM lParam

    khui_new_creds *         nc = NULL;
    khui_new_creds_by_type * nct = NULL;

    // We can define and use a structure like the following to
    // maintain the data that will be used to drive the dialog user
    // interface and to store credentials type settings:
    struct nc_dialog_data *  d = NULL;

    nc = (khui_new_creds *) lParam;

    // Now we can use nc to query for our credentials type structure
    khui_cw_find_type(nc, credtype_id, &nct);

    assert(nct);

    // The dialog data structure should live until we receive
    // WM_DESTROY.
    d = malloc(sizeof(*d));
    ZeroMemory(d, sizeof(*d));

    d->nc = nc;
    d->nct = nct;

    // Store it as our user data for the dialog.
    SetWindowLongPtr(hwnd, DWLP_USER, (LPARAM) d);

    // The aux member of the khui_new_creds_by_type structure is
    // reserved for use by the credentials provider.  We can use it to
    // store our dialog data.  This way, the dialog procedure and the
    // plug-in thread can both access it and use it to store
    // credential options for use when obtaining credentials.  The
    // dialog and the dialog data exist until KMSG_CRED_END is sent.
    nct->aux = (LPARAM) d;

    // We should return FALSE here to indicate that we don't want to
    // set keyboard focus to this dialog yet.  The application will
    // attempt to create all the credentials type panels as well as
    // the other child dialogs used for the new credentials opeartion.
    return FALSE;

WM_NC_NOTIFY

WM_NC_NOTIFY is a special window message that Network Identity Manager uses to communicate with credentials type panels. The messages are listed in the khui_wm_nc_notifications enumeration. The format of the message is as follows:

The WM_NC_NOTIFY notifications that a credentials provider is expected to handle are the following:

The primary identity has changed.

The khui_new_creds structure contains a list of identities to which the current operation should be applied. In its current implementation, only the first identity in this list is used. Therefore, the list will contain at most one identity. It is possible for the list to be empty (for example, if the user hasn't selected an identity yet).

When handling this notification, the plug-in should check the n_identities member of the khui_new_creds structure to see whether there are any identities selected. This value would be either zero or one. If it is non-zero, then a handle to the selected identity will be in khui_new_creds::identities[0].

Plug-ins typically use this notfication to load identity specific settings when a new identity is selected.

This notification is sent to all the credentials type panels.

The new credentials window has moved.

This message is sent to all the credentials type panels when the new credentials window is being moved. It will be sent continuously if the user is dragging the window. Plug-ins rarely need to know their position on the screen. However, if there are any other windows that were created by the plug-in, such as floating controls or tooltips, they may need to be repositioned in response to this message.

Sent to all the credentials type panels.

Update the credentials text associated with a panel.

During the new credentials operation, each plug-in is expected to maintain a textual representation of the credentials that the plug-in expects to obtain for the selected identity. It can, alternatively, be used to indicate the state of the credentials type in respect to the selected identity (for example, whether the credentials type is disabled for the identity and why).

This text is not visible when the new credentials window is in basic mode, but it is visible when the window is in advanced mode. The following image shows the expanded new credentials window including the credentials text from a several plug-ins:

new_creds_expanded.png

Once this message is received, each plug-in should construct its credentials text string and store it in the credtext member of its khui_new_creds_by_type structure as shown in the sample code below:

      // Handler for window message WM_NC_NOTIFY with
      // HWND hwnd, WPARAM wParam and LPARAM lParam

      // This structure holds the dialog data for the panel.  We
      // assume it has 'nc' and 'nct' fields that point to the
      // khui_new_creds and khui_new_creds_by_type structures
      // respectively.

      ...
      struct nc_dialog_data * d;
      ...

      // Retrieve the data structure from the dialog user data.
      d = (struct nc_dialog_data *) GetWindowLongPtr(hwnd, DWLP_USER);

      switch (HIWORD(wParam)) {
      case WMNC_UPDATE_CREDTEXT:
        {
          wchar_t buffer[KHUI_MAXCCH_LONG_DESC];
          size_t cb_size;

          // we are being requested to update the credentials text. We
          // already allocated a buffer when we created the nct
          // structure.  So we can just set the text here.

          // The credentials text should reflect the credentials that
          // will be obtained when the new credentials operation
          // completes.

          assert(d && d->nc && d->nct);

          if (d->nct->credtext) {
              free(d->nct->credtext);
              d->nct->credtext = NULL;
          }

          // We only display something if there is a selected identity
          if (d->nc->n_identities > 0) {
            StringCbPrintf(buffer, sizeof(buffer),
                           L"<p>My Credentials<tab>: %s</p>",
                           get_credential_name(d));
            StringCbLength(buffer, sizeof(buffer), &cb_size);
            cb_size += sizeof(wchar_t); // account for the terminating NULL

            d->nct->credtext = malloc(cb_size);
            if (d->nct->credtext) {
               StringCbCopy(d->nct->credtext, cb_size, buffer);
            }
          }

          break;
        }

      ... // Handler other notifications
      }

The text that is specified as the credentials text is formatted hypertext. For more information about support for formatting and hypertext and handling hyperlinks, see khui_htwnd.

Note:
When this message is sent to the new credentials window, the application will send the WMNC_UPDATE_CREDTEXT message to all the credential type panels and update the credential text window.

A hyperlink was activated.

Sent to a panel dialog procedure when a user clicks an embedded link in the credentials text that belongs to that panel. The lParam parameter of the message is a pointer to a khui_htwnd_link structure describing the link.

See also:
khui_htwnd
Note:
The lParam parameter does not point to a khui_new_creds structure for this message.

The credentials acquisition process is about to start.

Sent to all the credentials type panels to notify them that the credentials acquisition process will start. Once all plug-ins have handled the notification, the application will start sending out <KMSG_CRED, KMSG_CRED_PROCESS> messages to the credentials providers which are participating in the new credentials operation.

Other notes


Generated on Fri Aug 3 08:27:13 2007 for Network Identity Manager by Doxygen 1.5.2
© 2004-2007 Massachusetts Institute of Technology.
© 2005-2007 Secure Endpoints Inc.
Contact khimaira@mit.edu