# KIM Favorite Identities Documentation

## Functions

- kim_error_t kim_favorite_identities_create (kim_favorite_identities_t *out_favorite_identities)
    Create a new favorite identities list.
- kim_error_t kim_favorite_identities_copy (kim_favorite_identities_t *out_favorite_identities, kim_favorite_identities_t in_favorite_identities)
    Copy a favorite identities list.
- kim_error_t kim_favorite_identities_get_number_of_identities (kim_favorite_identities_t in_favorite_identities, kim_count_t *out_number_of_identities)
    Get the number of identities in a favorite identities list.
- kim_error_t kim_favorite_identities_get_identity_at_index (kim_favorite_identities_t in_favorite_identities, kim_count_t in_index, kim_identity_t *out_identity)
    Get the Nth identity in a favorite identities list.
- kim_error_t kim_favorite_identities_add_identity (kim_favorite_identities_t io_favorite_identities, kim_identity_t in_identity)
    Add an identity to a favorite identities list.
- kim_error_t kim_favorite_identities_remove_identity (kim_favorite_identities_t io_favorite_identities, kim_identity_t in_identity)
    Remove an identity from a identities list.
- kim_error_t kim_favorite_identities_remove_all_identities (kim_favorite_identities_t io_favorite_identities)
    Empty a favorite identities list.
- void kim_favorite_identities_free (kim_favorite_identities_t *io_favorite_identities)
    Free memory associated with an identities list.

## Function Documentation

kim_error_t kim_favorite_identities_create | ( | kim_favorite_identities_t * | out_favorite_identities | ) |

Create a new favorite identities list.

Parameters:

  | out_favorite_identities | on exit, a new favorite identities object. Must be freed with kim_favorite_identities_free().

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

kim_error_t kim_favorite_identities_copy | ( | kim_favorite_identities_t * | out_favorite_identities,
|  | kim_favorite_identities_t | in_favorite_identities |
| ) |  |  |

Copy a favorite identities list.

Parameters:

  | out_favorite_identities | on exit, a new favorite identities object which is a copy of in_favorite_identities. Must be freed with kim_favorite_identities_free().
  | in_favorite_identities | a favorite identities object.

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

kim_error_t kim_favorite_identities_get_number_of_identities | ( | kim_favorite_identities_t | in_favorite_identities,
|  | kim_count_t * | out_number_of_identities |
| ) |  |  |

Get the number of identities in a favorite identities list.

Parameters:

  | in_favorite_identities | a favorite identities object.
  | out_number_of_identities | on exit, the number of identities in in_favorite_identities.

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

kim_error_t kim_favorite_identities_get_identity_at_index | ( | kim_favorite_identities_t | in_favorite_identities,
|  | kim_count_t | in_index,
|  | kim_identity_t * | out_identity |
| ) |  |  |

Get the Nth identity in a favorite identities list.

Parameters:

  | in_favorite_identities | a favorite identities object.
  | in_index | a index into the identities list (starting at 0).
  | out_realm | on exit, the identity at in_index in in_favorite_identities. Must be freed with kim_string_free().

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

kim_error_t kim_favorite_identities_add_identity | ( | kim_favorite_identities_t | io_favorite_identities,
|  | kim_identity_t | in_identity |
| ) |  |  |

Add an identity to a favorite identities list.

Parameters:

  | io_favorite_identities | a favorite identities object.
  | in_identity | an identity string to add to in_favorite_identities.

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

kim_error_t kim_favorite_identities_remove_identity | ( | kim_favorite_identities_t | io_favorite_identities,
|  | kim_identity_t | in_identity |
| ) |  |  |

Remove an identity from a identities list.

Parameters:

  | io_favorite_identities | a favorite identities object.
  | in_identity | an identity to remove from in_favorite_identities.

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

kim_error_t kim_favorite_identities_remove_all_identities | ( | kim_favorite_identities_t | io_favorite_identities | ) |

Empty a favorite identities list.

Parameters:

  | io_favorite_identities | a favorite identities object.

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

void kim_favorite_identities_free | ( | kim_favorite_identities_t * | io_favorite_identities | ) |

Free memory associated with an identities list.

Parameters:

  | io_favorite_identities | the favorite identities object to be freed. Set to NULL on exit.