Revision control
Copy as Markdown
/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
[Custom]
typedef string Url;
[Custom]
typedef i64 PlacesTimestamp;
[Custom]
typedef i32 VisitTransitionSet;
[Custom]
typedef string Guid;
namespace places {
[Throws=PlacesApiError]
PlacesApi places_api_new(string db_path);
};
enum ConnectionType {
"ReadOnly",
"ReadWrite",
"Sync", // ideally we wouldn't need to expose this and should guard against it being used (it's internal only)
};
interface SqlInterruptHandle {
void interrupt();
};
interface PlacesApi {
[Throws=PlacesApiError]
PlacesConnection new_connection(ConnectionType conn_type);
[Self=ByArc]
void register_with_sync_manager();
[Throws=PlacesApiError]
void reset_history();
[Throws=PlacesApiError]
string history_sync(string key_id, string access_token, string sync_key, Url tokenserver_url);
[Throws=PlacesApiError]
string bookmarks_sync(string key_id, string access_token, string sync_key, Url tokenserver_url);
[Throws=PlacesApiError]
void bookmarks_reset();
};
interface PlacesConnection {
SqlInterruptHandle new_interrupt_handle();
[Throws=PlacesApiError]
HistoryMetadata? get_latest_history_metadata_for_url(Url url);
[Throws=PlacesApiError]
sequence<HistoryMetadata> get_history_metadata_between(PlacesTimestamp start, PlacesTimestamp end);
[Throws=PlacesApiError]
sequence<HistoryMetadata> get_history_metadata_since(PlacesTimestamp since);
[Throws=PlacesApiError]
sequence<SearchResult> query_autocomplete(string search, i32 limit);
// `url` is a `string` and not a `URL` because `accept_result`
// handles malformed urls
[Throws=PlacesApiError]
void accept_result(string search_string, string url);
[Throws=PlacesApiError]
Url? match_url(string query);
[Throws=PlacesApiError]
sequence<HistoryMetadata> query_history_metadata(string query, i32 limit);
[Throws=PlacesApiError]
sequence<HistoryHighlight> get_history_highlights(HistoryHighlightWeights weights, i32 limit);
[Throws=PlacesApiError]
void note_history_metadata_observation(HistoryMetadataObservation data);
[Throws=PlacesApiError]
void metadata_delete(Url url, Url? referrer_url, string? search_term);
[Throws=PlacesApiError]
void metadata_delete_older_than(PlacesTimestamp older_than);
[Throws=PlacesApiError]
void apply_observation(VisitObservation visit);
[Throws=PlacesApiError]
sequence<Url> get_visited_urls_in_range(PlacesTimestamp start, PlacesTimestamp end, boolean include_remote);
[Throws=PlacesApiError]
sequence<HistoryVisitInfo> get_visit_infos(PlacesTimestamp start_date, PlacesTimestamp end_date, VisitTransitionSet exclude_types);
[Throws=PlacesApiError]
i64 get_visit_count(VisitTransitionSet exclude_types);
[Throws=PlacesApiError]
sequence<HistoryVisitInfo> get_visit_page(i64 offset, i64 count, VisitTransitionSet exclude_types);
// TODO: bound should be a `PlacesTimestamp`?
[Throws=PlacesApiError]
HistoryVisitInfosWithBound get_visit_page_with_bound(i64 bound, i64 offset, i64 count, VisitTransitionSet exclude_types);
[Throws=PlacesApiError]
sequence<boolean> get_visited(sequence<string> urls);
[Throws=PlacesApiError]
void delete_visits_for(string url);
[Throws=PlacesApiError]
void delete_visits_between(PlacesTimestamp start, PlacesTimestamp end);
[Throws=PlacesApiError]
void delete_visit(string url, PlacesTimestamp timestamp);
[Throws=PlacesApiError]
sequence<TopFrecentSiteInfo> get_top_frecent_site_infos(i32 num_items, FrecencyThresholdOption threshold_option);
//From a-c: will not remove any history from remote devices, but it will prevent deleted
// history from returning.
[Throws=PlacesApiError]
void delete_everything_history();
/// Run maintenance on the places DB (prune step)
///
/// The `run_maintenance_*()` functions are intended to be run during idle time and will take steps
/// to clean up / shrink the database. They're split up so that we can time each one in the
/// Kotlin wrapper code (This is needed because we only have access to the Glean API in Kotlin and
/// it supports a stop-watch style API, not recording specific values).
///
/// db_size_limit is the approximate storage limit in bytes. If the database is using more space
/// than this, some older visits will be deleted to free up space. Pass in a 0 to skip this.
///
/// prune_limit is the maximum number of visits to prune if the database is over db_size_limit
[Throws=PlacesApiError]
RunMaintenanceMetrics run_maintenance_prune(u32 db_size_limit, u32 prune_limit);
/// Run maintenance on the places DB (vacuum step)
///
/// The `run_maintenance_*()` functions are intended to be run during idle time and will take steps
/// to clean up / shrink the database. They're split up so that we can time each one in the
/// Kotlin wrapper code (This is needed because we only have access to the Glean API in Kotlin and
/// it supports a stop-watch style API, not recording specific values).
[Throws=PlacesApiError]
void run_maintenance_vacuum();
/// Run maintenance on the places DB (optimize step)
///
/// The `run_maintenance_*()` functions are intended to be run during idle time and will take steps
/// to clean up / shrink the database. They're split up so that we can time each one in the
/// Kotlin wrapper code (This is needed because we only have access to the Glean API in Kotlin and
/// it supports a stop-watch style API, not recording specific values).
[Throws=PlacesApiError]
void run_maintenance_optimize();
/// Run maintenance on the places DB (checkpoint step)
///
/// The `run_maintenance_*()` functions are intended to be run during idle time and will take steps
/// to clean up / shrink the database. They're split up so that we can time each one in the
/// Kotlin wrapper code (This is needed because we only have access to the Glean API in Kotlin and
/// it supports a stop-watch style API, not recording specific values).
[Throws=PlacesApiError]
void run_maintenance_checkpoint();
[Throws=PlacesApiError]
BookmarkItem? bookmarks_get_tree([ByRef] Guid item_guid);
[Throws=PlacesApiError]
BookmarkItem? bookmarks_get_by_guid([ByRef] Guid guid, boolean get_direct_children);
// XXX - should return BookmarkData
[Throws=PlacesApiError]
sequence<BookmarkItem> bookmarks_get_all_with_url(string url);
// XXX - should return BookmarkData
[Throws=PlacesApiError]
sequence<BookmarkItem> bookmarks_search(string query, i32 limit);
// XXX - should return BookmarkData
[Throws=PlacesApiError]
sequence<BookmarkItem> bookmarks_get_recent(i32 limit);
[Throws=PlacesApiError]
boolean bookmarks_delete(Guid id);
[Throws=PlacesApiError]
void bookmarks_delete_everything();
[Throws=PlacesApiError]
Url? bookmarks_get_url_for_keyword(string keyword);
[Throws=PlacesApiError]
void bookmarks_update(BookmarkUpdateInfo data);
[Throws=PlacesApiError]
Guid bookmarks_insert(InsertableBookmarkItem bookmark);
// Counts the number of bookmarks in the bookmark tree under the specified GUID. Does not count
// the passed item, so an empty folder will return zero, as will a non-existing GUID or the
// guid of a non-folder item.
// Counts only bookmark items - ie, sub-folders and separators are not counted.
[Throws=PlacesApiError]
u32 bookmarks_count_bookmarks_in_trees([ByRef] sequence<Guid> folder_guids);
[Throws=PlacesApiError]
HistoryMigrationResult places_history_import_from_ios(string db_path, i64 last_sync_timestamp);
};
/**
* Frecency threshold options for fetching top frecent sites. Requests a page that was visited
* with a frecency score greater or equal to the value associated with the enums
*/
enum FrecencyThresholdOption {
// Returns all visited pages. The frecency score is 0
"None",
// Skip visited pages that were only visited once. The frecency score is 101
"SkipOneTimePages",
};
dictionary RunMaintenanceMetrics {
boolean pruned_visits;
u32 db_size_before;
u32 db_size_after;
};
dictionary SearchResult {
Url url;
string title;
i64 frecency;
};
// Some kind of namespacing for uniffi would be ideal. Multiple udl/macro defns?
// Everything below is from the crate::storage::history_metadata module...
enum DocumentType {
// A page that isn't described by any other more specific types.
"Regular",
// A media page.
"Media",
};
enum VisitType {
// This transition type means the user followed a link.
"Link",
// This transition type means that the user typed the page's URL in the
// URL bar or selected it from UI (URL bar autocomplete results, etc)
"Typed",
"Bookmark",
"Embed",
"RedirectPermanent",
"RedirectTemporary",
"Download",
"FramedLink",
"Reload",
// Internal visit type used for meta data updates. Doesn't represent an actual page visit
"UpdatePlace",
};
// This is used as an "input" to the api.
dictionary HistoryMetadataObservation {
string url;
string? referrer_url = null;
string? search_term = null;
i32? view_time = null;
DocumentType? document_type = null;
string? title = null;
};
// This is what is returned.
dictionary HistoryMetadata {
string url;
string? title;
string? preview_image_url;
i64 created_at;
i64 updated_at;
i32 total_view_time;
string? search_term;
DocumentType document_type;
string? referrer_url;
};
dictionary HistoryHighlightWeights {
double view_time;
double frequency;
};
dictionary HistoryHighlight {
double score;
i32 place_id;
string url;
string? title;
string? preview_image_url;
};
dictionary HistoryVisitInfo {
Url url;
string? title;
PlacesTimestamp timestamp;
VisitType visit_type;
boolean is_hidden;
Url? preview_image_url;
boolean is_remote;
};
dictionary HistoryVisitInfosWithBound {
sequence<HistoryVisitInfo> infos;
i64 bound;
i64 offset;
};
/**
* Encapsulates either information about a visit to a page, or meta information about the page,
* or both. Use [VisitType.UPDATE_PLACE] to differentiate an update from a visit.
*/
dictionary VisitObservation {
Url url;
string? title = null;
VisitType? visit_type;
boolean? is_error = null;
boolean? is_redirect_source = null;
boolean? is_permanent_redirect_source = null;
PlacesTimestamp? at = null;
Url? referrer = null;
boolean? is_remote = null;
Url? preview_image_url = null;
};
// Exists just to convince uniffi to generate `liftSequence*` helpers!
dictionary Dummy {
sequence<HistoryMetadata>? md;
};
dictionary TopFrecentSiteInfo {
Url url;
string? title;
};
dictionary HistoryMigrationResult {
u32 num_total;
u32 num_succeeded;
u32 num_failed;
u64 total_duration;
};
[Error]
interface PlacesApiError {
UnexpectedPlacesException(string reason);
UrlParseFailed(string reason);
PlacesConnectionBusy(string reason);
OperationInterrupted(string reason);
UnknownBookmarkItem(string reason);
InvalidBookmarkOperation(string reason);
};
dictionary BookmarkData {
Guid guid;
Guid parent_guid;
u32 position;
PlacesTimestamp date_added;
PlacesTimestamp last_modified;
Url url;
string? title;
};
dictionary BookmarkSeparator {
Guid guid;
PlacesTimestamp date_added;
PlacesTimestamp last_modified;
Guid parent_guid;
u32 position;
};
dictionary BookmarkFolder {
Guid guid;
PlacesTimestamp date_added;
PlacesTimestamp last_modified;
Guid? parent_guid;
u32 position;
string? title;
sequence<Guid>? child_guids;
sequence<BookmarkItem>? child_nodes;
};
[Enum]
interface BookmarkItem {
Bookmark(BookmarkData b);
Separator(BookmarkSeparator s);
Folder(BookmarkFolder f);
};
dictionary BookmarkUpdateInfo {
Guid guid;
string? title;
string? url;
Guid? parent_guid;
u32? position;
};
// Structs for inserting new bookmark items.
// Where the item should be placed.
[Enum]
interface BookmarkPosition {
Specific(u32 pos);
Append();
};
dictionary InsertableBookmark {
Guid? guid = null;
Guid parent_guid;
BookmarkPosition position;
PlacesTimestamp? date_added = null;
PlacesTimestamp? last_modified = null;
Url url;
string? title = null;
};
dictionary InsertableBookmarkSeparator {
Guid? guid = null;
Guid parent_guid;
BookmarkPosition position;
PlacesTimestamp? date_added = null;
PlacesTimestamp? last_modified = null;
};
dictionary InsertableBookmarkFolder {
Guid? guid = null;
Guid parent_guid;
BookmarkPosition position;
PlacesTimestamp? date_added = null;
PlacesTimestamp? last_modified = null;
string? title = null;
sequence<InsertableBookmarkItem> children;
};
[Enum]
interface InsertableBookmarkItem {
Bookmark(InsertableBookmark b);
Folder(InsertableBookmarkFolder f);
Separator(InsertableBookmarkSeparator s);
};