KIM Selection Hints Reference Documentation

Defines

Functions

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.

Generated on Mon Nov 3 17:45:44 2008 for Kerberos Identity Management by  doxygen 1.5.3