Function notmuch_sys::notmuch_database_add_message [−] [src]

pub unsafe extern "C" fn notmuch_database_add_message(
    database: *mut notmuch_database_t, 
    filename: *const c_char, 
    message: *mut *mut notmuch_message_t
) -> notmuch_status_t

Add a new message to the given notmuch database or associate an additional filename with an existing message.

Here, 'filename' should be a path relative to the path of 'database' (see notmuch_database_get_path), or else should be an absolute filename with initial components that match the path of 'database'.

The file should be a single mail message (not a multi-message mbox) that is expected to remain at its current location, (since the notmuch database will reference the filename, and will not copy the entire contents of the file.

If another message with the same message ID already exists in the database, rather than creating a new message, this adds 'filename' to the list of the filenames for the existing message.

If 'message' is not NULL, then, on successful return (notmuch_status_t::SUCCESS or notmuch_status_t::DUPLICATE_MESSAGE_ID) '*message' will be initialized to a message object that can be used for things such as adding tags to the just-added message. The user should call notmuch_message_destroy when done with the message. On any failure '*message' will be set to NULL.

Return value:

  • notmuch_status_t::SUCCESS: Message successfully added to database.

  • notmuch_status_t::XAPIAN_EXCEPTION: A Xapian exception occurred, message not added.

  • notmuch_status_t::DUPLICATE_MESSAGE_ID: Message has the same message ID as another message already in the database. The new filename was successfully added to the message in the database (if not already present) and the existing message is returned.

  • notmuch_status_t::FILE_ERROR: an error occurred trying to open the file, (such as permission denied, or file not found, etc.). Nothing added to the database.

  • notmuch_status_t::FILE_NOT_EMAIL: the contents of filename don't look like an email message. Nothing added to the database.

  • notmuch_status_t::READ_ONLY_DATABASE: Database was opened in read-only mode so no message can be added.

  • notmuch_status_t::UPGRADE_REQUIRED: The caller must upgrade the database to use this function.