}
/** @brief Resolve an alias
- * @param Track name (might be an alias)
+ * @param track Track name (might be an alias)
* @return Real track name (definitely not an alias) or NULL if no such track
*/
const char *trackdb_resolve(const char *track) {
}
/* return 1 iff sorted tag lists A and B have at least one member in common */
+/** @brief Detect intersecting tag lists
+ * @param a First list of tags (NULL-terminated)
+ * @param b Second list of tags (NULL-terminated)
+ * @return 1 if @p a and @p b have at least one member in common
+ *
+ * @p a and @p must be sorted.
+ */
int tag_intersection(char **a, char **b) {
int cmp;
return 0;
}
+/** @brief Called when disorder-choose might have completed
+ * @param ev Event loop
+ * @param which @ref CHOOSE_RUNNING or @ref CHOOSE_READING
+ *
+ * Once called with both @p which values, @ref choose_callback is called
+ * (usually chosen_random_track()).
+ */
static void choose_finished(ev_source *ev, unsigned which) {
choose_complete |= which;
if(choose_complete != (CHOOSE_RUNNING|CHOOSE_READING))
choose_callback(ev, 0);
}
-/** @brief Called when @c disorder-choose terminates */
+/** @brief Called when @c disorder-choose terminates
+ * @param ev Event loop
+ * @param pid Process ID
+ * @param status Exit status
+ * @param rusage Resource usage
+ * @param u User data
+ * @return 0
+ */
static int choose_exited(ev_source *ev,
pid_t attribute((unused)) pid,
int status,
return 0;
}
-/** @brief Called with data from @c disorder-choose pipe */
+/** @brief Called with data from @c disorder-choose pipe
+ * @param ev Event loop
+ * @param reader Reader state
+ * @param ptr Data read
+ * @param bytes Number of bytes read
+ * @param eof Set at end of file
+ * @param u User data
+ * @return 0
+ */
static int choose_readable(ev_source *ev,
ev_reader *reader,
void *ptr,
return 0;
}
+/** @brief Called when @c disorder-choose pipe errors
+ * @param ev Event loop
+ * @param errno_value Error code
+ * @param u User data
+ * @return 0
+ */
static int choose_read_error(ev_source *ev,
int errno_value,
void attribute((unused)) *u) {
return 0;
}
-/* get a track name given the prefs. Set *used_db to 1 if we got the answer
- * from the prefs. */
+/** @brief Get a track name part, using prefs
+ * @param track Track name
+ * @param context Context ("display" etc)
+ * @param part Part ("album" etc)
+ * @param p Preference
+ * @param used_db Set if a preference is used
+ * @return Name part (never NULL)
+ *
+ * Used by compute_alias() and trackdb_getpart().
+ */
static const char *getpart(const char *track,
const char *context,
const char *part,
return result;
}
-/* get a track name part, like trackname_part(), but taking the database into
- * account. */
+/** @brief Get a track name part
+ * @param track Track name
+ * @param context Context ("display" etc)
+ * @param part Part ("album" etc)
+ * @return Name part (never NULL)
+ *
+ * This is interface used by c_part().
+ */
const char *trackdb_getpart(const char *track,
const char *context,
const char *part) {
return getpart(actual, context, part, p, &used_db);
}
-/* get the raw path name for @track@ (might be an alias) */
+/** @brief Get the raw (filesystem) path for @p track
+ * @param track track Track name (can be an alias)
+ * @return Raw path (never NULL)
+ *
+ * The raw path is the actual bytes that came out of readdir() etc.
+ */
const char *trackdb_rawpath(const char *track) {
DB_TXN *tid;
struct kvp *t;
/* return true if the basename of TRACK[0..TL-1], as defined by DL, matches RE.
* If RE is a null pointer then it matches everything. */
+/** @brief Match a track against a rgeexp
+ * @param dl Length of directory part of track
+ * @param track Track name
+ * @param tl Length of track name
+ * @param re Regular expression or NULL
+ * @return Nonzero on match
+ *
+ * @p tl is the total length of @p track, @p dl is the length of the directory
+ * part (the index of the final "/"). The subject of the regexp match is the
+ * basename, i.e. the part after @p dl.
+ *
+ * If @p re is NULL then always matches.
+ */
static int track_matches(size_t dl, const char *track, size_t tl,
const pcre *re) {
int ovec[3], rc;
}
}
+/** @brief Generate a list of tracks and/or directories in @p dir
+ * @param v Where to put results
+ * @param dir Directory to list
+ * @param what Bitmap of objects to return
+ * @param re Regexp to filter matches (or NULL to accept all)
+ * @param tid Owning transaction
+ * @return 0 or DB_LOCK_DEADLOCK
+ */
static int do_list(struct vector *v, const char *dir,
enum trackdb_listable what, const pcre *re, DB_TXN *tid) {
DBC *cursor;
return err;
}
-/* return the directories or files below @dir@ */
+/** @brief Get the directories or files below @p dir
+ * @param dir Directory to list
+ * @param np Where to put number of results (or NULL)
+ * @param what Bitmap of objects to return
+ * @param re Regexp to filter matches (or NULL to accept all)
+ * @return List of tracks
+ */
char **trackdb_list(const char *dir, int *np, enum trackdb_listable what,
const pcre *re) {
DB_TXN *tid;
return v.vec;
}
-/* If S is tag:something, return something. Else return 0. */
+/** @brief Detect a tag element in a search string
+ * @param s Element of search string
+ * @return Pointer to tag name (in @p s) if this is a tag: search, else NULL
+ *
+ * Tag searches take the form "tag:TAG".
+ */
static const char *checktag(const char *s) {
if(!strncmp(s, "tag:", 4))
return s + 4;
/* trackdb_scan **************************************************************/
+/** @brief Visit every track
+ * @param root Root to scan or NULL for all
+ * @param callback Callback for each track
+ * @param u Passed to @p callback
+ * @param tid Owning transaction
+ * @return 0, DB_LOCK_DEADLOCK or EINTR
+ *
+ * Visits every track and calls @p callback. @p callback will get the track
+ * data and preferences and should return 0 to continue scanning or EINTR to
+ * stop.
+ */
int trackdb_scan(const char *root,
int (*callback)(const char *track,
struct kvp *data,
}
}
+/** @brief Cancel a rescan
+ * @return Nonzero if a rescan was cancelled
+ */
int trackdb_rescan_cancel(void) {
if(rescan_pid == -1) return 0;
if(kill(rescan_pid, SIGTERM) < 0)
/* global prefs **************************************************************/
+/** @brief Set a global preference
+ * @param name Global preference name
+ * @param value New value
+ * @param who Who is setting it
+ */
void trackdb_set_global(const char *name,
const char *value,
const char *who) {
}
}
+/** @brief Set a global preference
+ * @param name Global preference name
+ * @param value New value
+ * @param tid Owning transaction
+ */
int trackdb_set_global_tid(const char *name,
const char *value,
DB_TXN *tid) {
return 0;
}
+/** @brief Get a global preference
+ * @param name Global preference name
+ * @return Value of global preference, or NULL if it's not set
+ */
const char *trackdb_get_global(const char *name) {
DB_TXN *tid;
int err;
return r;
}
+/** @brief Get a global preference
+ * @param name Global preference name
+ * @param tid Owning transaction
+ * @param rp Where to store value (will get NULL if preference not set)
+ * @return 0 or DB_LOCK_DEADLOCK
+ */
int trackdb_get_global_tid(const char *name,
DB_TXN *tid,
const char **rp) {
/* tidying up ****************************************************************/
+/** @brief Do database garbage collection
+ *
+ * Called form periodic_database_gc().
+ */
void trackdb_gc(void) {
int err;
char **logfiles;
/* user database *************************************************************/
-/** @brief Return true if @p user is trusted */
+/** @brief Return true if @p user is trusted
+ * @param user User to look up
+ * @return Nonzero if they are in the 'trusted' list
+ *
+ * Now used only in upgrade from old versions.
+ */
static int trusted(const char *user) {
int n;
}
/** @brief Return non-zero for a valid username
+ * @param user Candidate username
+ * @return Nonzero if it's valid
*
* Currently we only allow the letters and digits in ASCII. We could be more
* liberal than this but it is a nice simple test. It is critical that
return 1;
}
-/** @brief Add a user */
+/** @brief Add a user
+ * @param user Username
+ * @param password Initial password or NULL
+ * @param rights Initial rights
+ * @param email Email address or NULL
+ * @param confirmation Confirmation string to require
+ * @param tid Owning transaction
+ * @param flags DB flags e.g. DB_NOOVERWRITE
+ * @return 0, DB_KEYEXIST or DB_LOCK_DEADLOCK
+ */
static int create_user(const char *user,
const char *password,
const char *rights,
return trackdb_putdata(trackdb_usersdb, user, k, tid, flags);
}
-/** @brief Add one pre-existing user */
+/** @brief Add one pre-existing user
+ * @param user Username
+ * @param password password
+ * @param tid Owning transaction
+ * @return 0, DB_KEYEXIST or DB_LOCK_DEADLOCK
+ *
+ * Used only in upgrade from old versions.
+ */
static int one_old_user(const char *user, const char *password,
DB_TXN *tid) {
const char *rights;
tid, DB_NOOVERWRITE);
}
+/** @brief Upgrade old users
+ * @param tid Owning transaction
+ * @return 0 or DB_LOCK_DEADLOCK
+ */
static int trackdb_old_users_tid(DB_TXN *tid) {
int n;
~mdw / disorder / commitdiff