makary/bookmarkfs
1
0
Fork 0
mirror of https://git.sr.ht/~cismonx/bookmarkfs synced 2025-06-07 19:58:50 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

doc: update backend API

Browse source 
Add doc for the `bookmark_set` function.
This commit is contained in:
CismonX 2025-02-12 12:34:10 +08:00
parent 87931bc1f7
commit a7575dc074
No known key found for this signature in database
GPG key ID: 3094873E29A482FB
1 changed files with 97 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

97
doc/bookmarkfs.texi
View file

@ -2372,6 +2372,103 @@ Indicates that the cookie is obtained from @code{bookmark_list} or
@end table
@node Set Bookmark Content
@subsection Set Bookmark Content
The @code{bookmark_set} function is called to update the data associated
with a bookmark or bookmark-related object.
It is never called when the filesystem is mounted read-only.
Type of the @code{bookmark_set} function is defined as:
@example c
typedef int (bookmarkfs_bookmark_set_func) (
void *backend_ctx,
uint64_t id,
char const *attr_key,
uint32_t flags,
void const *val,
size_t val_len
);
@end example
Function arguments:
@table @code
@item backend_ctx
The pointer referring to the backend context.
@item id
ID of the object to update.
@item attr_key
Name of an extended attribute.
If not @code{NULL}, @code{attr_key} is guaranteed to be a NUL-terminated
string, and the function should update the corresponding extended attribute
value instead of the bookmark content.
@item flags
A bit array of the following flags:
@table @code
@item BOOKMARKFS_BOOKMARK_SET_TIME
Indicates that the function should update the timestamps associated with
the object.
The @code{val} argument points to an array of @code{struct timespec},
the first element refers to the last access time, and the second element
refers to the last modification time of the object.
Values of @code{attr_key} and @code{val_len} are unspecified.
The @code{tv_nsec} field of each timestamp may be @code{UTIME_OMIT},
which indicates that the timestamp should be left as-is.
It is guaranteed not to be @code{UTIME_NOW}.
If this flag is not set, the function should update the bookmark content
or extended attribute value instead.
@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
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.
@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.
@end table
@end table
@item val
New value for the object data.
@item val_len
Length of the new value in bytes.
@end table
On success, the function should return @t{0}.
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
when the bookmark content is actually modified, and always explicitly
updates the mtime after a writeback.
However, if the @code{BOOKMARKFS_BACKEND_CTIME} flag is set for this context,
the backend should automatically update the bookmark mtime to
the current time upon extended attribute update.
@node Sync Bookmarks
@subsection Sync Bookmarks