KIM Selection Hints Reference Documentation

Functions

Function Documentation

kim_error_t kim_selection_hints_create (  kim_selection_hints_t *  out_selection_hints,
kim_string_t  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 object representing the failure.

kim_error_t kim_selection_hints_copy (  kim_selection_hints_t *  out_selection_hints,
kim_selection_hints_t  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 object representing the failure.

kim_error_t kim_selection_hints_set_service_identity (  kim_selection_hints_t  io_selection_hints,
kim_identity_t  in_service_identity
) 
 

Set the preferred service identity.

Parameters:
io_selection_hints a selection hints object to modify.
in_service_identity a service identity.
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
See also:
kim_selection_hints_get_service_identity()

kim_error_t kim_selection_hints_get_service_identity (  kim_selection_hints_t  in_selection_hints,
kim_identity_t *  out_service_identity
) 
 

Get the preferred service identity.

Parameters:
in_selection_hints a selection hints object.
out_service_identity on exit, the service identity specified in in_selection_hints. Must be freed with kim_identity_free().
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
See also:
kim_selection_hints_set_service_identity()

kim_error_t kim_selection_hints_set_client_realm (  kim_selection_hints_t  io_selection_hints,
kim_string_t  in_client_realm
) 
 

Set the preferred client realm.

Parameters:
io_selection_hints a selection hints object to modify.
in_client_realm a client realm string.
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
See also:
kim_selection_hints_get_client_realm()

kim_error_t kim_selection_hints_get_client_realm (  kim_selection_hints_t  io_selection_hints,
kim_string_t *  out_client_realm
) 
 

Get the preferred client realm.

Parameters:
io_selection_hints a selection hints object.
out_client_realm on exit, the client realm string specified in in_selection_hints. Must be freed with kim_string_free().
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
See also:
kim_selection_hints_set_client_realm()

kim_error_t kim_selection_hints_set_user (  kim_selection_hints_t  io_selection_hints,
kim_string_t  in_user
) 
 

Set the preferred user name.

Parameters:
io_selection_hints a selection hints object to modify.
in_user a user name string.
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
See also:
kim_selection_hints_get_user()

kim_error_t kim_selection_hints_get_user (  kim_selection_hints_t  in_selection_hints,
kim_string_t *  out_user
) 
 

Get the preferred user name.

Parameters:
in_selection_hints a selection hints object.
out_user on exit, the user name string specified in in_selection_hints. Must be freed with kim_string_free().
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
See also:
kim_selection_hints_set_user()

kim_error_t kim_selection_hints_set_service_realm (  kim_selection_hints_t  io_selection_hints,
kim_string_t  in_service_realm
) 
 

Set the preferred service realm.

Parameters:
io_selection_hints a selection hints object to modify.
in_service_realm a service realm string.
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
See also:
kim_selection_hints_get_service_realm()

kim_error_t kim_selection_hints_get_service_realm (  kim_selection_hints_t  io_selection_hints,
kim_string_t *  out_service_realm
) 
 

Get the preferred service realm.

Parameters:
io_selection_hints a selection hints object.
out_service_realm on exit, the service realm string specified in in_selection_hints. Must be freed with kim_string_free().
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
See also:
kim_selection_hints_set_service_realm()

kim_error_t kim_selection_hints_set_service (  kim_selection_hints_t  io_selection_hints,
kim_string_t  in_service
) 
 

Set the preferred service name.

Parameters:
io_selection_hints a selection hints object to modify.
in_service a service name string.
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
See also:
kim_selection_hints_get_service()

kim_error_t kim_selection_hints_get_service (  kim_selection_hints_t  in_selection_hints,
kim_string_t *  out_service
) 
 

Get the preferred service name.

Parameters:
in_selection_hints a selection hints object.
out_service on exit, the service name string specified in in_selection_hints. Must be freed with kim_string_free().
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
See also:
kim_selection_hints_set_service()

kim_error_t kim_selection_hints_set_hostname (  kim_selection_hints_t  io_selection_hints,
kim_string_t  in_hostname
) 
 

Set the preferred server host name.

Parameters:
io_selection_hints a selection hints object to modify.
in_hostname a server host name string.
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
See also:
kim_selection_hints_get_hostname()

kim_error_t kim_selection_hints_get_hostname (  kim_selection_hints_t  in_selection_hints,
kim_string_t *  out_hostname
) 
 

Get the preferred server host name.

Parameters:
in_selection_hints a selection hints object.
out_hostname on exit, the server host name string specified in in_selection_hints. Must be freed with kim_string_free().
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
See also:
kim_selection_hints_set_hostname()

kim_error_t kim_selection_hints_set_application_name (  kim_selection_hints_t  io_selection_hints,
kim_string_t  in_application_name
) 
 

Set the application name for use in user interaction.

Parameters:
io_selection_hints a selection hints object to modify.
in_application_name a localized string containing the full name of the application.
Note:
If you do not call this function KIM will attempt to determine the application name at runtime. If that fails (the functionality is only available on some platforms) then KIM will use the application identity string.
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
See also:
kim_selection_hints_get_application_name()

kim_error_t kim_selection_hints_get_application_name (  kim_selection_hints_t  in_selection_hints,
kim_string_t *  out_application_name
) 
 

Get the application name for use in user interaction.

Parameters:
in_selection_hints a selection hints object.
out_application_name on exit, the localized full name of the application specified in in_selection_hints. Must be freed with kim_string_free().
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
See also:
kim_selection_hints_set_application_name()

kim_error_t kim_selection_hints_set_explanation (  kim_selection_hints_t  io_selection_hints,
kim_string_t  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. You may still need to call kim_selection_hints_set_application_name()
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
See also:
kim_selection_hints_get_explanation()

kim_error_t kim_selection_hints_get_explanation (  kim_selection_hints_t  in_selection_hints,
kim_string_t *  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 object representing the failure.
See also:
kim_selection_hints_set_explanation()

kim_error_t kim_selection_hints_set_options (  kim_selection_hints_t  io_selection_hints,
kim_options_t  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 object representing the failure.
See also:
kim_selection_hints_get_options()

kim_error_t kim_selection_hints_get_options (  kim_selection_hints_t  in_selection_hints,
kim_options_t *  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 object representing the failure.
See also:
kim_selection_hints_set_options()

kim_error_t kim_selection_hints_set_allow_user_interaction (  kim_selection_hints_t  in_selection_hints,
kim_boolean_t  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 object representing the failure.
Note:
This setting defaults to TRUE.
See also:
kim_selection_hints_get_allow_user_interaction

kim_error_t kim_selection_hints_get_allow_user_interaction (  kim_selection_hints_t  in_selection_hints,
kim_boolean_t *  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 object representing the failure.
Note:
This setting defaults to TRUE.
See also:
kim_selection_hints_set_allow_user_interaction

kim_error_t kim_selection_hints_set_use_cached_results (  kim_selection_hints_t  in_selection_hints,
kim_boolean_t  in_use_cached_results
) 
 

Set whether or not KIM will cache mappings generated by this selection hints object.

Parameters:
in_selection_hints a selection hints object to modify
in_use_cached_results 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 object representing the failure.
Note:
This setting defaults to TRUE.
See also:
kim_selection_hints_get_use_cached_results

kim_error_t kim_selection_hints_get_use_cached_results (  kim_selection_hints_t  in_selection_hints,
kim_boolean_t *  out_use_cached_results
) 
 

Get whether or not KIM will cache mappings generated by this selection hints object.

Parameters:
in_selection_hints a selection hints object to modify
out_use_cached_results 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 object representing the failure.
Note:
This setting defaults to TRUE.
See also:
kim_selection_hints_set_use_cached_results

kim_error_t kim_selection_hints_get_identity (  kim_selection_hints_t  in_selection_hints,
kim_identity_t *  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 object 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_t kim_selection_hints_cache_results (  kim_selection_hints_t  in_selection_hints,
kim_identity_t  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 object representing the failure.

kim_error_t kim_selection_hints_forget_cached_results (  kim_selection_hints_t  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 object representing the failure.

void kim_selection_hints_free (  kim_selection_hints_t *  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.