diff --git a/doc/bookmarkfs.texi b/doc/bookmarkfs.texi index 9f4dd54..f1d48e9 100644 --- a/doc/bookmarkfs.texi +++ b/doc/bookmarkfs.texi @@ -1656,8 +1656,8 @@ A bit array of the following flags: @table @code @item BOOKMARKFS_BACKEND_READONLY -Indicates that the filesystem is mounted read-only, and the frontend program -will not call functions that may write to the bookmark storage. +Indicates that the filesystem is mounted read-only, and the functions that +may write to the bookmark storage will not be called for this session. @item BOOKMARKFS_BACKEND_CTIME Indicates that the @option{-o ctime} option is given to @@ -1799,7 +1799,7 @@ A bit array of the following flags: Indicates that the backend claims exclusive access to the bookmark storage. In exclusive mode, modifications to the bookmark storage only come from -the frontend, and the frontend program may perform optimizations based on +the frontend, and the caller may perform optimizations based on this assumption. @item BOOKMARKFS_BACKEND_HAS_KEYWORD @@ -1930,12 +1930,12 @@ Function arguments: The pointer referring to the backend context. @item id -The subsystem object ID to be used for lookup. +ID of the object to be used for lookup. It could either be a bookmark ID or a tag ID, depending on the value of @code{flags}. @item name -Name of the subsystem object to lookup. +Name of the object to lookup. It could be a bookmark name, tag name or keyword name, depending on the value of @code{flags}. @@ -2049,7 +2049,7 @@ Function arguments: The pointer referring to the backend context. @item id -The subsystem object ID of the directory. +Object ID of the directory. It could either be a bookmark ID or a tag ID, depending on the value of @code{flags}. @@ -2282,7 +2282,7 @@ Length of @code{value} in bytes. @end table The function returns @t{0} on success. -Otherwise, the function returns a nagated @code{errno} which should be +Otherwise, the function returns a negated @code{errno} which should be used as the return value for the current @code{bookmark_get} call. @item user_data @@ -2438,18 +2438,18 @@ Equals to one of the following values (after shifting): Update the data associated with a bookmark or bookmark folder. @xref{Bookmarks}. -Value of @code{id} refers to the ID of a bookmark or bookmark folder. +@code{id} refers to the ID of a bookmark or bookmark folder. @item BOOKMARKFS_BOOKMARK_TYPE_TAG Update the data associated with a tag. @xref{Tags}. -Value of @code{id} refers to the ID of a tag folder. +@code{id} refers to the ID of a tag folder. @end table @end table @item val -New value for the object data. +Pointer to the new value of the object data. @item val_len Length of the new value in bytes. @@ -2460,7 +2460,7 @@ Otherwise, it should return a negated @code{errno} indicating the error encountered. The backend does not need to update the last modification time of a bookmark -upon bookmark content update, since the frontend program knows better +upon bookmark content update, since the caller knows better when the bookmark content is actually modified, and always explicitly updates the mtime after a writeback. @@ -2469,6 +2469,114 @@ the backend should automatically update the bookmark mtime to the current time upon extended attribute update. +@node Create Bookmark +@subsection Create Bookmark + +The @code{bookmark_create} function is called to create a new bookmark +or bookmark-related object. +It is never called when the filesystem is mounted read-only. + +Type of the @code{bookmark_create} function is defined as: + +@example c +typedef int (bookmarkfs_bookmark_create_func) ( + void *backend_ctx, + uint64_t parent_id, + char const *name, + uint32_t flags, + struct bookmarkfs_bookmark_stat *stat_buf +); +@end example + +Function arguments: + +@table @code +@item backend_ctx +The pointer referring to the backend context. + +@item parent_id +ID of the parent directory where the new object shall be created. + +@item name +Name of the new object. + +@item flags +A bit array of the following flags: + +@table @code +@item BOOKMARKFS_BOOKMARK_CREATE_DIR +Indicates that the new object to be created should be a directory. + +If this flag is not set, the new object should be a bookmark. + +@item BOOKMARKFS_BOOKMARK_TYPE_MASK +The subsystem to operate on. + +Equals to one of the following values (after shifting): + +@table @code +@item BOOKMARKFS_BOOKMARK_TYPE_BOOKMARK +Create a bookmark or bookmark folder. +@xref{Bookmarks}. + +@code{parent_id} refers to the ID of the parent bookmark folder. + +@item BOOKMARKFS_BOOKMARK_TYPE_TAG +Create a tag folder, or associate an existing bookmark with a tag. +@xref{Tags}. + +@code{parent_id} refers to the ID of the parent tag folder. + +@item BOOKMARKFS_BOOKMARK_TYPE_KEYWORD +Associate an existing bookmark with a new keyword. +@xref{Keywords}. + +The value of @code{parent_id} is unspecified. +@end table +@end table + +@item stat_buf +Attributes of the new object. + +@xref{Bookmark Attributes} for the definition of the +@code{bookmarkfs_bookmark_stat} structure. + +Except for the @code{id} field, the initial content of this argument +is unspecified. +When the object is successfully found, the backend should populate +this argument with appropriate values. + +When associating an existing bookmark with a tag or keyword, the initial +value of the @code{id} field refers to the bookmark to be associated. +Generally it should be left as-is, but the backend is allowed to +re-assign it to the ID of another bookmark (see below for restrictions). +@end table + +On success, the function should return @t{0}. +Otherwise, it should return a negated @code{errno} indicating the error +encountered. + +Restrictions for the new object: + +@table @asis +@item new bookmark +Bookmark content should be empty if possible. + +Other reasonable values (e.g., @samp{about:blank}) are also acceptable +if the bookmark storage does not allow empty bookmark content. + +@item new directory +Should not contain any entries. + +@item new association +Should appear to be the same object as the associated bookmark, +or at least contain the same content. +@end table + +When a new object is successfully created, the backend should automatically +update the last modification time of the parent directory to the current time. + + @node Sync Bookmarks @subsection Sync Bookmarks