api survey

API conventions

Rust API conventions in the deltachat-core-rust library.

Survey

A survey of existing APIs used to create the main objects. The APIs as shown are not actual signatures, but only approximations that allow to compare their behaviour without the full complexity.

Questions:

• Any main types missing?
• Any constructors missing?

In-Memory Only

• These are infallible.

ChatId::new(id: u32);
// -> Self
MsgId::new(id: u32);  // Also MsgId::new_unset()
// -> Self
Message::new(viewtype: ViewType);
// -> Self

Read from DB by ID, error if not there

• Err are failures that could not be handled.

Contact::load_from_db(context: &Context, contact_id: u32);
// -> Result<Self>
Chat::load_from_db(context: &Context, chat_id: ChatId);
// -> Result<Self>
Message::load_from_db(context: &Context, id: MsgId);
// -> Result<Message>

Upsert

• These update an existing entry if there is one, otherwise insert a new entry.
• Err are failures that could not be handled.

// Value of origin decides what's overwritten
// Signals if something was modified.
Contact::add_or_lookup(context: &Context, name: &str, addr: &str, origin: Origin);
//-> Result<(u32, Modifier)>

// Wrapper around Contact::add_or_lookup()
// Assumes it was an explicit user action and does some more stuff like unblock.
Contact::create(context: &Context, name: &str, addr: &str);
// -> Result<u32>

Lookups or Searches

• Searches existing entries.
• Err are failures that could not be handled.
• Option/None for not found (or empty list).

Contact::lookup_id_by_addr(context: &Context, addr: &str, min_origin: Origin);
// -> Result<Option<u32>>
Contact::get_all(context: &Context, listflags: u32, query: &str);
// -> Result<Vec<u32>>

// Whoops, guess we swallow errors.
Contact::get_all_blocked(context: &Context);
// -> Vec<u32>

// Whoops, we can't represent not found due to lack of None
chat::lookup_by_contact_id(context: &Context, contact_id: u32);
// -> Result<(ChatId, Blocked)>

Other

• These all do multiple things and are meant to be triggered by user actions

// Will also unblock etc.  Similar to Contact::create seems to imply user action
chat::create_by_contact_id(context: &Context, contact_id: u32);
// -> Result<ChatId>

// Will also unblock etc.  Also explicit user action
chat::create_by_msg_id(context: &Context, msg_id: MsgId);
// -> Result<ChatId>

chat::create_group_chat(context: &Context, protect: ProtectionStatus, chat_name: &str);
// -> Result<ChatId>
chat::create_or_lookup_by_contact_id(context: &Context, contact_id: u32, create_blocked: Blocked);
//-> Result<(ChatId, Blocked)>

BlobObject::create(context: &Context, suggested_name: &str, data: &[u8]);
// -> Result<Self>