Using Contexts

Obtaining the context

Typically, messages sent by actions that rely on UI context will obtain and store the context in a location that is accessible to the handlers of the message.

If a plug-in needs to obtain the UI context, it should do so by calling khui_context_get() and passing in a pointer to a khui_action_context structure.

Once obtained, the contents of the khui_action_context structure should be considered read-only. When the plug-in is done with the structure, it should call khui_context_release(). This cleans up any additional memory allocated for storing the context as well as releasing all the objects that were referenced from the context.

Selection context

The selection context is specified in the khui_action_context structure in the sel_creds and n_sel_creds fields. These combined provide an array of handles to credentials which are selected.

Note:

If n_sel_creds is zero, then sel_creds may be NULL.

Cursor context

The scope of the cursor context is specified in the scope field of the khui_action_context strucutre. The scope can be one of:

• KHUI_SCOPE_NONE
• KHUI_SCOPE_IDENT
• KHUI_SCOPE_CREDTYPE
• KHUI_SCOPE_GROUP
• KHUI_SCOPE_CRED

Depending on the scope, several other members of the strucre may also be set.

In general, the cursor context can be a single credential or an entire outline level. Unlike the selection context, since this specifies a single point of selection it can not be disjointed.

The contents of the identity, cred_type, cred, headers and n_headers are described in the documentation of each of the scope values above.

KHUI_SCOPE_GROUP

The KHUI_SCOPE_GROUP scope is the generic scope which describes a cursor selection that can not be simplified into any other scope.

In this case, the selection is described by an array of khui_header elements each of which specify a criterion for narrowing down the selection of credentials. The khui_header structure specifies an attribute in the attr_id field and a value in the data and cb_data fields. The credentials that are selected are those in the root credential set whose repective attributes contain the values specified in each of the khui_header elements.

For example, the following selection:

will result in the following header specification:

    ctx.n_headers = 3;

    ctx.headers[0].attr_id = KCDB_ATTR_LOCATION;
    ctx.headers[0].data = L"grailauth@KHMTEST";
    ctx.headers[0].cb_data = sizeof(L"grailauth@KHMTEST");

    ctx.headers[1].attr_id = KCDB_ATTR_ID;
    ctx.headers[1].data = &handle_to_identity;
    ctx.headers[1].cb_data = sizeof(khm_handle);

    ctx.headers[2].attr_id = KCDB_ATTR_TYPE;
    ctx.headers[2].data = &kerberos_5_credtype;
    ctx.headers[2].cb_data = sizeof(khm_int32);

Note:

The attribute that is used to specify the header is not the display attribute, but the canonical attribute. For example, in the above, the second header was actually KCDB_ATTR_ID_NAME. But KCDB_ATTR_ID was used since that is the canonical source for KCDB_ATTR_ID_NAME. See kcdb_attrib for more information on canonical attributes.

---