Network Identity Manager: Writing the dialog procedure for a cred type panel

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

    // 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

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

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

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:

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.

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.

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.

Writing the dialog procedure for a cred type panel

Handling Messages

WM_INITDIALOG

WM_NC_NOTIFY

Other notes