add_persona_from_details

Add a new Persona to the PersonaStore.

The Persona will be created by the PersonaStore backend from the key-value pairs given in details.

All additions through this function will later be emitted through the personas-changed signal to be notified of the new Persona. The return value is purely for convenience, since it can be complicated to correlate the provided details with the final Persona.

If the store is offline (or PersonaStore.prepare hasn't yet been called successfully), this function will throw PersonaStoreError.STORE_OFFLINE. It's the responsibility of the caller to cache details and re-try this function if it wishes to make offline adds work.

If the details are not recognised or are invalid, PersonaStoreError.INVALID_ARGUMENT will be thrown. A default set of possible details are defined by Folks.PersonaDetail but backends can either support a subset or superset of the suggested defaults.

If a Persona with the given details already exists in the store, no error will be thrown and this function will return null.

Parameters:

details

a key-value map of details to use in creating the new Persona

Returns:

the new Persona or null if the corresponding Persona already existed. If non-null, the new Persona will also be amongst the Persona(s) in a future emission of PersonaStore.personas_changed.

Exceptions:

PersonaStoreError

if adding the persona failed