# KIM Selection Hints Reference Documentation

## Defines

- #define kim_hint_key_client_realm "kim_hint_key_client_realm"
- #define kim_hint_key_user "kim_hint_key_user"
- #define kim_hint_key_service_realm "kim_hint_key_service_realm"
- #define kim_hint_key_service "kim_hint_key_service"
- #define kim_hint_key_server "kim_hint_key_server"
- #define kim_hint_key_service_identity "kim_hint_key_service_identity"

## Functions

- kim_error kim_selection_hints_create (kim_selection_hints *out_selection_hints, kim_string in_application_identifier)
    Create a new selection hints object.
- kim_error kim_selection_hints_copy (kim_selection_hints *out_selection_hints, kim_selection_hints in_selection_hints)
    Copy a selection hints object.
- kim_error kim_selection_hints_set_hint (kim_selection_hints io_selection_hints, kim_string in_hint_key, kim_string in_hint_string)
    Set the string value of a hint used for identity selection.
- kim_error kim_selection_hints_get_hint (kim_selection_hints in_selection_hints, kim_string in_hint_key, kim_string *out_hint_string)
    Get the string value of a hint used for identity selection.
- kim_error kim_selection_hints_set_explanation (kim_selection_hints io_selection_hints, kim_string in_explanation)
    Set the strings used to prompt the user to select the identity.
- kim_error kim_selection_hints_get_explanation (kim_selection_hints in_selection_hints, kim_string *out_explanation)
    Get the strings used to prompt the user to select the identity.
- kim_error kim_selection_hints_set_options (kim_selection_hints io_selection_hints, kim_options in_options)
    Set the options which will be used if credentials need to be acquired.
- kim_error kim_selection_hints_get_options (kim_selection_hints in_selection_hints, kim_options *out_options)
    Get the options which will be used if credentials need to be acquired.
- kim_error kim_selection_hints_set_allow_user_interaction (kim_selection_hints in_selection_hints, kim_boolean in_allow_user_interaction)
    Set whether or not KIM may interact with the user to select an identity.
- kim_error kim_selection_hints_get_allow_user_interaction (kim_selection_hints in_selection_hints, kim_boolean *out_allow_user_interaction)
    Get whether or not KIM may interact with the user to select an identity.
- kim_error kim_selection_hints_set_remember_identity (kim_selection_hints in_selection_hints, kim_boolean in_remember_identity)
    Set whether or not KIM will use cached mappings for this selection hints object.
- kim_error kim_selection_hints_get_remember_identity (kim_selection_hints in_selection_hints, kim_boolean *out_remember_identity)
    Get whether or not KIM will use cache mappings for this selection hints object.
- kim_error kim_selection_hints_get_identity (kim_selection_hints in_selection_hints, kim_identity *out_identity)
    Choose a client identity based on selection hints.
- kim_error kim_selection_hints_remember_identity (kim_selection_hints in_selection_hints, kim_identity in_identity)
    Add an entry for the selection hints to the selection hints cache, replacing any existing entry.
- kim_error kim_selection_hints_forget_identity (kim_selection_hints in_selection_hints)
    Remove an entry for the selection hints from the selection hints cache.
- void kim_selection_hints_free (kim_selection_hints *io_selection_hints)
    Free memory associated with a selection hints object.

## Define Documentation

#define kim_hint_key_client_realm "kim_hint_key_client_realm"

A client identity in this realm. See KIM Selection Hints Overview for more information

#define kim_hint_key_user "kim_hint_key_user"

A client identity whose first component is this user string. See KIM Selection Hints Overview for more information

#define kim_hint_key_service_realm "kim_hint_key_service_realm"

A client identity which has obtained a service credential for this realm. See KIM Selection Hints Overview for more information

#define kim_hint_key_service "kim_hint_key_service"

A client identity which has obtained a service credential for this service. See KIM Selection Hints Overview for more information

#define kim_hint_key_server "kim_hint_key_server"

A client identity which has obtained a service credential for this server. See KIM Selection Hints Overview for more information

#define kim_hint_key_service_identity "kim_hint_key_service_identity"

The client identity which has obtained a service credential for this service identity. See KIM Selection Hints Overview for more information

## Function Documentation

kim_error kim_selection_hints_create | ( | kim_selection_hints * | out_selection_hints,
|  | kim_string | in_application_identifier |
| ) |  |  |

Create a new selection hints object.

Parameters:

  | out_selection_hints | on exit, a new selection hints object. Must be freed with kim_selection_hints_free().
  | in_application_identifier | an application identifier string. Java-style identifiers are recommended to avoid cache entry collisions (eg: "com.example.MyApplication")

Returns:
  On success, KIM_NO_ERROR. On failure, an error code representing the failure.

kim_error kim_selection_hints_copy | ( | kim_selection_hints * | out_selection_hints,
|  | kim_selection_hints | in_selection_hints |
| ) |  |  |

Copy a selection hints object.

Parameters:

  | out_selection_hints | on exit, a new selection hints object which is a copy of in_selection_hints. Must be freed with kim_selection_hints_free().
  | in_selection_hints | a selection hints object.

Returns:
  On success, KIM_NO_ERROR. On failure, an error code representing the failure.

kim_error kim_selection_hints_set_hint | ( | kim_selection_hints | io_selection_hints,
|  | kim_string | in_hint_key,
|  | kim_string | in_hint_string |
| ) |  |  |

Set the string value of a hint used for identity selection.

Parameters:

  | io_selection_hints | a selection hints object to modify.
  | in_hint_key | A string representing the type of hint to set.
  | in_hint_string | A string representation of a hint for in_hint_key to set in in_selection_hints.

Returns:
  On success, KIM_NO_ERROR. On failure, an error code representing the failure.

See also:
  kim_selection_hints_get_hint()

kim_error kim_selection_hints_get_hint | ( | kim_selection_hints | in_selection_hints,
|  | kim_string | in_hint_key,
|  | kim_string * | out_hint_string |
| ) |  |  |

Get the string value of a hint used for identity selection.

Parameters:

  | in_selection_hints | a selection hints object.
  | in_hint_key | A string representing the type of hint to obtain.
  | out_hint_string | On exit, a string representation of the hint in_hint_key in in_selection_hints. If the hint is not set, sets the value pointed to by out_hint_string to NULL; Must be freed with kim_string_free().

Returns:
  On success, KIM_NO_ERROR. On failure, an error code representing the failure.

See also:
  kim_selection_hints_set_hint()

kim_error kim_selection_hints_set_explanation | ( | kim_selection_hints | io_selection_hints,
|  | kim_string | in_explanation |
| ) |  |  |

Set the strings used to prompt the user to select the identity.

Parameters:

  | io_selection_hints | a selection hints object to modify.
  | in_explanation | a localized string describing why the caller needs the identity.

Note:
  If the application only does one thing (the reason it needs an identity is obvious) then you may not need to call this function.

Returns:
  On success, KIM_NO_ERROR. On failure, an error code representing the failure.

See also:
  kim_selection_hints_get_explanation()

kim_error kim_selection_hints_get_explanation | ( | kim_selection_hints | in_selection_hints,
|  | kim_string * | out_explanation |
| ) |  |  |

Get the strings used to prompt the user to select the identity.

Parameters:

  | in_selection_hints | a selection hints object.
  | out_explanation | on exit, the localized string specified in in_selection_hints which describes why the caller needs the identity. May be NULL. If non-NULL, must be freed with kim_string_free().

Returns:
  On success, KIM_NO_ERROR. On failure, an error code representing the failure.

See also:
  kim_selection_hints_set_explanation()

kim_error kim_selection_hints_set_options | ( | kim_selection_hints | io_selection_hints,
|  | kim_options | in_options |
| ) |  |  |

Set the options which will be used if credentials need to be acquired.

Parameters:

  | io_selection_hints | a selection hints object to modify.
  | in_options | options to control credential acquisition.

Returns:
  On success, KIM_NO_ERROR. On failure, an error code representing the failure.

See also:
  kim_selection_hints_get_options()

kim_error kim_selection_hints_get_options | ( | kim_selection_hints | in_selection_hints,
|  | kim_options * | out_options |
| ) |  |  |

Get the options which will be used if credentials need to be acquired.

Parameters:

  | in_selection_hints | a selection hints object.
  | out_options | on exit, the options to control credential acquisition specified in in_selection_hints. May be KIM_OPTIONS_DEFAULT. If not, must be freed with kim_options_free().

Returns:
  On success, KIM_NO_ERROR. On failure, an error code representing the failure.

See also:
  kim_selection_hints_set_options()

kim_error kim_selection_hints_set_allow_user_interaction | ( | kim_selection_hints | in_selection_hints,
|  | kim_boolean | in_allow_user_interaction |
| ) |  |  |

Set whether or not KIM may interact with the user to select an identity.

Parameters:

  | in_selection_hints | a selection hints object to modify
  | in_allow_user_interaction | a boolean value specifying whether or not KIM should ask the user to select an identity for in_selection_hints.

Returns:
  On success, KIM_NO_ERROR. On failure, an error code representing the failure.

Note:
  This setting defaults to TRUE.

See also:
  kim_selection_hints_get_allow_user_interaction

kim_error kim_selection_hints_get_allow_user_interaction | ( | kim_selection_hints | in_selection_hints,
|  | kim_boolean * | out_allow_user_interaction |
| ) |  |  |

Get whether or not KIM may interact with the user to select an identity.

Parameters:

  | in_selection_hints | a selection hints object to modify
  | out_allow_user_interaction | on exit, a boolean value specifying whether or not KIM should ask the user to select an identity for in_selection_hints.

Returns:
  On success, KIM_NO_ERROR. On failure, an error code representing the failure.

Note:
  This setting defaults to TRUE.

See also:
  kim_selection_hints_set_allow_user_interaction

kim_error kim_selection_hints_set_remember_identity | ( | kim_selection_hints | in_selection_hints,
|  | kim_boolean | in_remember_identity |
| ) |  |  |

Set whether or not KIM will use cached mappings for this selection hints object.

Parameters:

  | in_selection_hints | a selection hints object to modify
  | in_remember_identity | a boolean value specifying whether or not KIM should use a cached mapping between in_selection_hints and a Kerberos identity.

Returns:
  On success, KIM_NO_ERROR. On failure, an error code representing the failure.

Note:
  This setting defaults to TRUE.

See also:
  kim_selection_hints_get_remember_identity

kim_error kim_selection_hints_get_remember_identity | ( | kim_selection_hints | in_selection_hints,
|  | kim_boolean * | out_remember_identity |
| ) |  |  |

Get whether or not KIM will use cache mappings for this selection hints object.

Parameters:

  | in_selection_hints | a selection hints object to modify
  | out_remember_identity | on exit, a boolean value specifying whether or not KIM will use a cached mapping between in_selection_hints and a Kerberos identity.

Returns:
  On success, KIM_NO_ERROR. On failure, an error code representing the failure.

Note:
  This setting defaults to TRUE.

See also:
  kim_selection_hints_set_remember_identity

kim_error kim_selection_hints_get_identity | ( | kim_selection_hints | in_selection_hints,
|  | kim_identity * | out_identity |
| ) |  |  |

Choose a client identity based on selection hints.

Parameters:

  | in_selection_hints | the selection hints to add to the cache.
  | out_identity | the Kerberos identity in_selection_hints maps to. Must be freed with kim_identity_free().

Returns:
  On success, KIM_NO_ERROR. On failure, an error code representing the failure.

Note:
  out_identity is the identity mapped to by the current state of in_selection_hints. This function may prompt the user via a GUI to choose that identity. Subsequent modifications to in_selection_hints will not change out_identity.

kim_error kim_selection_hints_remember_identity | ( | kim_selection_hints | in_selection_hints,
|  | kim_identity | in_identity |
| ) |  |  |

Add an entry for the selection hints to the selection hints cache, replacing any existing entry.

Parameters:

  | in_selection_hints | the selection hints to add to the cache.
  | in_identity | the Kerberos identity in_selection_hints maps to.

Returns:
  On success, KIM_NO_ERROR. On failure, an error code representing the failure.

kim_error kim_selection_hints_forget_identity | ( | kim_selection_hints | in_selection_hints | ) |

Remove an entry for the selection hints from the selection hints cache.

Parameters:

  | in_selection_hints | the selection hints to remove from the cache.

Returns:
  On success, KIM_NO_ERROR. On failure, an error code representing the failure.

void kim_selection_hints_free | ( | kim_selection_hints * | io_selection_hints | ) |

Free memory associated with a selection hints object.

Parameters:

  | io_selection_hints | the selection hints object to be freed. Set to NULL on exit.