mirror of
https://git.sr.ht/~cismonx/bookmarkfs
synced 2025-06-07 19:58:50 +00:00
doc: update backend API
- Add doc for the `bookmark_list` function. - Other misc changes.
This commit is contained in:
CismonX
parent
88e38bd38e
commit
5286cda051
1 changed files with 200 additions and 9 deletions
|
|
@ -886,6 +886,8 @@ for the sake of simplicity.
|
|||
Additionally, bookmarks with such names are hidden from the filesystem
|
||||
until fixed with fsck (@pxref{Filesystem Check}).
|
||||
|
||||
@anchor{Directory Entry Ordering}
|
||||
@cindex Directory Entry Ordering
|
||||
@item Ordering of directory entries
|
||||
POSIX does not specify the ordering of the directory entries retrieved from
|
||||
the directory stream using @posixfuncmanpage{readdir}.
|
||||
|
|
@ -1482,8 +1484,8 @@ does not support the corresponding features.
|
|||
@node Initialize Backend
|
||||
@subsection Initialize Backend
|
||||
|
||||
The @code{backend_init} function is called by the frontend program
|
||||
before calling any other functions (except for @code{backend_info}).
|
||||
The @code{backend_init} function is called before any other functions
|
||||
(except for @code{backend_info}).
|
||||
If not @code{NULL}, it is guaranteed to be called exactly once
|
||||
throughout the lifetime of the process.
|
||||
|
||||
|
|
@ -1525,8 +1527,9 @@ The function should return @t{0} on success, and @t{-1} on error.
|
|||
@node Get Backend Information
|
||||
@subsection Get Backend Information
|
||||
|
||||
If not @code{NULL}, the @code{backend_info} function is called when the user
|
||||
instructs the frontend program to print information about the backend.
|
||||
The @code{backend_info} function is called to print information
|
||||
about the backend.
|
||||
It can be @code{NULL}.
|
||||
|
||||
When this function is called, the backend should write a human-readable
|
||||
message of the corresponding information to standard output.
|
||||
|
|
@ -1616,7 +1619,7 @@ struct bookmarkfs_backend_conf @{
|
|||
@table @code
|
||||
@item version
|
||||
Version number of the frontend program, equivalent to the
|
||||
@code{BOOKMARKFS_VERNUM} macro in @file{bookmarkfs/version.h}.
|
||||
@code{BOOKMARKFS_VERNUM} macro in @file{@var{$@{pkgincludedir@}}/version.h}.
|
||||
|
||||
@item flags
|
||||
A bit array of the following flags:
|
||||
|
|
@ -1922,19 +1925,19 @@ Equals to one of the following values (after shifting):
|
|||
|
||||
@table @code
|
||||
@item BOOKMARKFS_BOOKMARK_TYPE_BOOKMARK
|
||||
Indicates that the function should operate on the ``bookmarks'' subsystem.
|
||||
Lookup a bookmark or bookmark folder.
|
||||
@xref{Bookmarks}.
|
||||
|
||||
@code{id} and @code{name} refers to bookmark ID and bookmark name.
|
||||
|
||||
@item BOOKMARKFS_BOOKMARK_TYPE_TAG
|
||||
Indicates that the function should operate on the ``tags'' subsystem.
|
||||
Lookup a tag, or a bookmark under a tag.
|
||||
@xref{Tags}.
|
||||
|
||||
@code{id} and @code{name} refers to tag ID and tag name.
|
||||
|
||||
@item BOOKMARKFS_BOOKMARK_TYPE_KEYWORD
|
||||
Indicates that the function should operate on the ``keywords'' subsystem.
|
||||
Lookup a keyword.
|
||||
@xref{Keywords}.
|
||||
|
||||
@code{name} refers to keyword name (must not be @code{NULL}).
|
||||
|
|
@ -1949,6 +1952,7 @@ The initial content of this argument is unspecified.
|
|||
When the object is successfully found, the backend should populate
|
||||
this argument with appropriate values.
|
||||
|
||||
@anchor{Bookmark Attributes}
|
||||
The @code{bookmarkfs_bookmark_stat} structure is defined as:
|
||||
|
||||
@example c
|
||||
|
|
@ -1985,6 +1989,192 @@ but the backend may return other error codes which it sees fit.
|
|||
Also @pxref{Error Codes}.
|
||||
|
||||
|
||||
@node List Bookmarks
|
||||
@subsection List Bookmarks
|
||||
|
||||
The @code{bookmark_list} function is called to list the bookmarks or
|
||||
bookmark-related objects under a directory.
|
||||
It must not be @code{NULL}.
|
||||
|
||||
Type of the @code{bookmark_list} function is defined as:
|
||||
|
||||
@example c
|
||||
typedef int (bookmarkfs_bookmark_list_func) (
|
||||
void *backend_ctx,
|
||||
uint64_t id,
|
||||
off_t off,
|
||||
uint32_t flags,
|
||||
bookmarkfs_bookmark_list_cb *callback,
|
||||
void *user_data,
|
||||
void **cookie_ptr
|
||||
);
|
||||
@end example
|
||||
|
||||
Function arguments:
|
||||
|
||||
@table @code
|
||||
@item backend_ctx
|
||||
The pointer referring to the backend context.
|
||||
|
||||
@item id
|
||||
The subsystem object ID of the directory.
|
||||
It could either be a bookmark ID or a tag ID,
|
||||
depending on the value of @code{flags}.
|
||||
|
||||
@item off
|
||||
Position of the current @code{bookmark_list} operation, equivalent to
|
||||
the second argument for @posixfuncmanpage{seekdir}.
|
||||
|
||||
Initially, the value is always @t{0}.
|
||||
Subsequent calls (with the same cookie) use the values obtained from
|
||||
@code{entry->off} of @code{callback} function calls.
|
||||
If not, the position is unspecified.
|
||||
|
||||
A subsequent call with a @t{0} value indicates @code{rewinddir()}.
|
||||
|
||||
@item flags
|
||||
A bit array of the following flags:
|
||||
|
||||
@table @code
|
||||
@item BOOKMARKFS_BOOKMARK_LIST_WITHSTAT
|
||||
Indicates that the caller requires the attributes of the objects in the list.
|
||||
|
||||
@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
|
||||
List bookmarks (and bookmark folders) under a bookmark folder.
|
||||
@xref{Bookmarks}.
|
||||
|
||||
Value of @code{id} refers to the ID of a bookmark folder.
|
||||
|
||||
@item BOOKMARKFS_BOOKMARK_TYPE_TAG
|
||||
List tags, or bookmarks under a tag.
|
||||
@xref{Tags}.
|
||||
|
||||
Value of @code{id} refers to the ID of a tag folder.
|
||||
|
||||
@item BOOKMARKFS_BOOKMARK_TYPE_KEYWORD
|
||||
List keywords.
|
||||
@xref{Keywords}.
|
||||
|
||||
Value of @code{id} is unspecified.
|
||||
@end table
|
||||
@end table
|
||||
|
||||
@item callback
|
||||
Function to be called for each object found under the directory.
|
||||
|
||||
Ordering of the objects should follow the ordering of which they appear
|
||||
in the browser.
|
||||
@xref{Directory Entry Ordering}.
|
||||
|
||||
Type of the @code{callback} function is defined as:
|
||||
|
||||
@example c
|
||||
typedef int (bookmarkfs_bookmark_list_cb) (
|
||||
void *user_data,
|
||||
struct bookmarkfs_bookmark_entry const *entry
|
||||
);
|
||||
@end example
|
||||
|
||||
Function arguments:
|
||||
|
||||
@table @code
|
||||
@item user_data
|
||||
Must be equal to the @code{user_data} argument value for the current
|
||||
@code{bookmark_list} call.
|
||||
|
||||
@item entry
|
||||
Information of this object.
|
||||
|
||||
The @code{bookmarkfs_bookmark_entry} structure is defined as:
|
||||
|
||||
@example c
|
||||
struct bookmarkfs_bookmark_entry @{
|
||||
char const *name;
|
||||
off_t off;
|
||||
|
||||
struct bookmarkfs_bookmark_stat stat;
|
||||
@};
|
||||
@end example
|
||||
|
||||
@table @code
|
||||
@item name
|
||||
Name of the object entry.
|
||||
Must be a valid filename.
|
||||
|
||||
Objects with invalid name should be exempted from the list.
|
||||
@xref{Filesystem Check}.
|
||||
|
||||
@item off
|
||||
Position of the current entry, to be used for subsequent calls to
|
||||
@code{bookmark_list}.
|
||||
|
||||
@item stat
|
||||
Attributes of the object entry.
|
||||
|
||||
@xref{Bookmark Attributes} for the definition of the
|
||||
@code{bookmarkfs_bookmark_stat} structure.
|
||||
|
||||
If the @code{BOOKMARKFS_BOOKMARK_LIST_WITHSTAT} flag is @emph{not} given,
|
||||
the caller ignores @code{atime} and @code{mtime}, and only use @code{value_len}
|
||||
to determine whether the entry refers to a directory.
|
||||
@end table
|
||||
|
||||
Values of @code{entry} and @code{name} only need to be valid
|
||||
until the @code{callback} function returns.
|
||||
@end table
|
||||
|
||||
Return value:
|
||||
|
||||
@table @asis
|
||||
@item @t{0}
|
||||
Continue to the next entry, if one exists.
|
||||
|
||||
@item Non-zero value
|
||||
Stop listing entries, and use this value as the return value for
|
||||
the current @code{bookmark_list} call.
|
||||
@end table
|
||||
|
||||
@item user_data
|
||||
An opaque pointer which should be passed as-is to the @code{callback} function.
|
||||
|
||||
@item cookie_ptr
|
||||
Pointer to the ``cookie'' for the current @code{bookmark_list} operation.
|
||||
@code{NULL} if not used by the caller.
|
||||
|
||||
The ``cookie'' is an opaque pointer which stores internal states
|
||||
to be used for subsequent operations on the same directory.
|
||||
|
||||
If the value pointed to by @code{cookie_ptr} is @code{NULL}, it indicates
|
||||
that this is an initial operation.
|
||||
The backend should set the value to a pointer which is not @code{NULL}.
|
||||
|
||||
The backend must not change the cookie value.
|
||||
@end table
|
||||
|
||||
Return value:
|
||||
|
||||
@table @asis
|
||||
@item @t{0}
|
||||
All entries in the directory have been listed.
|
||||
|
||||
@item Negated @code{errno}
|
||||
An error occurred.
|
||||
|
||||
@item Arbitrary non-zero value
|
||||
The function is terminated by a call to @code{callback} that
|
||||
returns a non-zero value.
|
||||
@end table
|
||||
|
||||
If returning a negative value, the position of the current
|
||||
@code{bookmark_list} operation is unspecified.
|
||||
|
||||
|
||||
@node Create Bookmark Storage
|
||||
@subsection Create Bookmark Storage
|
||||
|
||||
|
|
@ -1993,7 +2183,8 @@ program to create a new bookmark storage.
|
|||
It can be @code{NULL}.
|
||||
|
||||
The new bookmark storage should be able to be opened directly, by both
|
||||
@code{backend_create} and the application that owns the bookmark storage.
|
||||
@code{backend_create} and the application that owns the bookmark storage
|
||||
(typically a web browser).
|
||||
|
||||
Type of the @code{backend_mkfs} function is defined as:
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue