Permalink
Find file
Fetching contributors…
Cannot retrieve contributors at this time
445 lines (444 sloc) 12.8 KB
.TH apetag 3 "2012-07-03"
.SH NAME
.B apetag
\- APEv2 tag reader/writer/updater
.SH SYNOPSIS
.B #include <apetag.h>
.P
.B struct ApeTag * ApeTag_new(FILE *file, uint32_t flags);
.P
.B int ApeTag_free(struct ApeTag *tag);
.P
.B int ApeTag_exists(struct ApeTag *tag);
.P
.B int ApeTag_exists_id3(struct ApeTag *tag);
.P
.B int ApeTag_remove(struct ApeTag *tag);
.P
.B int ApeTag_raw(struct ApeTag *tag, char **raw, uint32_t *raw_size);
.P
.B int ApeTag_parse(struct ApeTag *tag);
.P
.B int ApeTag_update(struct ApeTag *tag);
.P
.B int ApeTag_add_item(struct ApeTag *tag, struct ApeItem *item);
.P
.B int ApeTag_replace_item(struct ApeTag *tag, struct ApeItem *item);
.P
.B int ApeTag_remove_item(struct ApeTag *tag, const char *key);
.P
.B int ApeTag_clear_items(struct ApeTag *tag);
.P
.B struct ApeItem * ApeTag_get_item(struct ApeTag *tag, const char *key);
.P
.B struct ApeItem ** ApeTag_get_items(struct ApeTag *tag, uint32_t *item_count);
.P
.B int ApeTag_iter_items(struct ApeTag *tag, int iterator(struct ApeTag *tag, struct ApeItem *item, void *data), void *data);
.P
.B uint32_t ApeTag_size(struct ApeTag *tag);
.P
.B uint32_t ApeTag_item_count(struct ApeTag *tag);
.P
.B uint32_t ApeTag_file_item_count(struct ApeTag *tag);
.P
.B enum ApeTag_errcode ApeTag_error_code(struct ApeTag *tag);
.P
.B const char * ApeTag_error(struct ApeTag *tag);
.P
.B size_t ApeTag_get_max_size(void);
.P
.B size_t ApeTag_get_max_item_count(void);
.P
.B void ApeTag_set_max_size(uint32_t size);
.P
.B void ApeTag_set_max_item_count(uint32_t item_count);
.P
.B int ApeTag_mt_init(void);
.SH DESCRIPTION
.SS QUICK INTRO
.BR apetag 's
API is fairly straight forward. Some common things to remember:
.IP \(bu 2
For the public functions that return an
.BR int ,
-1 is always represents an error.
You can find the general area of error by calling
.BR ApeTag_error_code ,
which returns a member of the
.B ApeTag_errcode
enum.
You can get more detail about the specific error by calling
.BR ApeTag_error ,
which returns a
.B char*
describing the specific error (or in some cases, the underlying system function
that returned an error).
The members of the
.B ApeTag_errcode
enum are:
.IP \(bu 4
.BR APETAG_NOERR :
No error has yet occurred for this tag.
.IP \(bu 4
.BR APETAG_FILEERR :
An error occurred while dealing with the tag's file (reading/writing/etc.).
.IP \(bu 4
.BR APETAG_INTERNALERR :
An internal library error occurred.
.IP \(bu 4
.BR APETAG_LIMITEXCEEDED :
An attempt was made to read or write a tag with that violates the library's
limit for tag size or item count.
.IP \(bu 4
.BR APETAG_DUPLICATEITEM :
An attempt was made to add a duplicate item to an existing tag, or to parse
a tag containing a duplicate item.
.IP \(bu 4
.BR APETAG_CORRUPTTAG :
The tag could not be parsed as some part of it was corrupt.
.IP \(bu 4
.BR APETAG_INVALIDITEM :
An attempt was made to add an invalid item to an existing tag, or to parse
a tag containing an invalid item.
.IP \(bu 4
.BR APETAG_ARGERR :
A function was passed an argument that is not valid.
One cause of this is if a function was passed a NULL pointer argument
where a non-NULL pointer argument is required.
Note that since the error code is stored in the tag object, if you pass a
NULL tag argument, apetag will just return -1 (since there is nowhere to
record the type of error in that case).
.IP \(bu 4
.BR APETAG_NOTPRESENT :
The item to be removed or returned was not present in the tag.
.IP \(bu 2
ApeItem keys are NULL-terminated strings.
.IP \(bu 2
ApeItem values are unterminated strings, since they can contain '\\0'.
The size of the value is stored in the
.IR ApeItem 's
size.
.IP \(bu 2
All
.IR ApeItem s
and their keys and values must be stored on the heap.
.SS DATA STRUCTURES
The
.B apetag
library exists to read/write/update APEv2 tags in files.
The library is written in an object oriented fashion,
using two C structures:
.P
#include <apetag.h>
.P
struct ApeTag;
.br
.P
Almost all functions in the library accept an
.I struct ApeTag *
as the first argument.
.I ApeTag
is an opaque structure used by the library.
It is created using
.BR "ApeTag_new" .
Each tag can contain multiple
.IR ApeItem s,
one for each item (key/value) in the tag.
.I ApeItem
is defined as:
.P
typedef struct {
uint32_t size; /* Size of the value */
uint32_t flags; /* Flags on the item */
char *key; /* NULL-terminated string */
char *value; /* Unterminated string */
.br
} ApeItem;
.P
Adding new items to the tag requires creating the
.I ApeItem
manually,
using
.B malloc
for both the
.I ApeItem
itself, as well as its key and value,
as all must be stored on the heap. A pointer to the item can then be passed to
.BR ApeTag_add_item
to add the item to the tag.
.SS FUNCTIONS
.B struct ApeTag * ApeTag_new(FILE *file, uint32_t flags);
.P
Returns a new
.IR ApeTag
object associated with the given
.I file
and
.IR flags .
The only flag the should be passed is
.IR APE_NO_ID3 ,
which tells the library to ignore any existing ID3 tag when reading
a tag, and not to write an ID3 tag when updating.
.P
Returns a valid
.I ApeTag
if successful; otherwise a null pointer is returned.
.P
.B int ApeTag_free(struct ApeTag *tag);
.P
Frees all data associated with the
.IR tag ,
except for the file pointer.
This includes freeing all related
.IR ApeItem s
and their keys and values.
Since you pass the file pointer to
.BR ApeTag_new ,
you are expected to free it yourself.
.P
Returns 0 if successful, and -1 if there were errors.
Note that you can't call
.BR ApeTag_error
on error, as the
.I tag
has already been freed.
.P
.B int ApeTag_exists(struct ApeTag *tag);
.P
Checks if the file associated with
.I tag
already contains a valid APE tag.
.P
Returns 1 if an APE tag exists, 0 if it does not, -1 on error.
.P
.B int ApeTag_exists_id3(struct ApeTag *tag);
.P
Checks if the file associated with
.I tag
already contains a valid ID3v1 tag.
.P
Returns 1 if an ID3v1 tag exists, 0 if it does not, -1 on error.
.P
.B int ApeTag_remove(struct ApeTag *tag);
.P
Removes the APE tag from the file associated with
.IR tag ,
if the file has one.
.P
This function parses the header and footer of the tag and will error instead
of removing a tag if the header or footer of the tag is corrupt.
.P
Returns 1 if the tag doesn't exist, 0 if it does exist and the tag was
removed successfully, -1 on error.
.P
.B int ApeTag_raw(struct ApeTag *tag, char **raw, uint32_t *raw_size);
.P
Sets
.IR *raw
to the raw data for the entire tag (including ID3v1 data if an ID3v1 would
also be written), and sets
.IR raw_size
to the the length of the raw data.
.P
The caller is responsible for
freeing
.IR *raw.
.P
Returns 0 on success, -1 on error.
.P
.B int ApeTag_parse(struct ApeTag *tag);
.P
Parses the tag to get the actual items. This should be called before
.BR ApeTag_add_item
and
.BR ApeTag_update ,
unless you don't care about the existing items in the file (i.e. you are
just replacing the entire tag with new items).
.P
This is basically the same as calling
.BR ApeTag_add_item
manually with each item already in the tag.
.P
Returns 0 on success, -1 on error.
.P
.B int ApeTag_update(struct ApeTag *tag);
.P
Writes the new tag data (what
.BR ApeTag_raw
would return) to the
.IR FILE *
passed to
.BR ApeTag_new ,
replacing the current tag.
Note that
.BR ApeTag_parse
should be called before this method, unless you want to want to replace
the current tag (if one exists) with a completely new tag.
.P
Writes an ID3v1 tag as well as an APEv2 tag unless the
.I APE_NO_ID3
flag is used or the file already has an APEv2
tag but doesn't have an ID3v1 tag.
.P
Returns 0 on success, -1 on error.
.P
.B int ApeTag_add_item(struct ApeTag *tag, struct ApeItem *item);
.P
Adds a item to the tag.
The item cannot already exist in the tag, otherwise it will return
an error without changing the item.
The
.I item
itself, as well as
.I item->key
and
.IR item->value ,
must be created on the heap, as they are all freed when calling
.BR ApeTag_free ,
.BR ApeTag_clear_items ,
or
.BR ApeTag_remove_item .
.P
Returns 0 on success, -1 on error.
.P
.B int ApeTag_replace_item(struct ApeTag *tag, struct ApeItem *item);
.P
If an item with the matching key does not already exist in the tag,
this is the same as
.BR ApeTag_add_item .
Otherwise, if the item already exists, remove the existing item
and replace it with the given item.
.P
Returns 0 on success if the item doesn't exist, 1 on success if it already
existed, -1 on error.
.P
.B int ApeTag_remove_item(struct ApeTag *tag, const char *key);
.P
Removes the item with a matching key from the tag.
.P
Returns 0 on success, 1 if the item did not exist in the tag, -1 on error.
.P
.B int ApeTag_clear_items(struct ApeTag *tag);
.P
Frees all items stored in the tag.
.P
Returns 0 on success, -1 on error.
.P
.B struct ApeItem * ApeTag_get_item(struct ApeTag *tag, const char *key);
.P
Returns a pointer to the item matching the given key.
If there is no matching item, NULL is returned and the error code is set
to
.BR APETAG_NOTPRESENT .
For other errors, NULL is returned and the error code is set appropriately.
.P
The returned pointer should not be freed by the caller.
.P
.B struct ApeItem ** ApeTag_get_items(struct ApeTag *tag, uint32_t *item_count);
.P
Returns a array of
.BR ApeItem* s
for all items in the tag.
The array returned is unsorted and items returned are not necessarily returned
in the order they are stored in the file.
If
.BR item_count
is not NULL, it is set to the number of items in the array.
The returned array is always terminated by NULL, and always contains at least
1 item (which is NULL if the tag has no items).
.P
It is the caller's responsibility to free the returned array, but the individual
items in the array should not be freed by the caller.
.P
Returns 0 on success, -1 on error.
.P
.B int ApeTag_iter_items(struct ApeTag *tag, int iterator(struct ApeTag *tag, struct ApeItem *item, void *data), void *data);
.P
Iterates over all of the items in the tag.
For each item in the tag, calls the iterator function with the tag,
a pointer to the item, and the data pointer passed to the function.
The data pointer is not used by the library, but it allows the iterator
function to communicate back to the calling function.
.P
The iterator function should return 0 to continue iteration. Any other value
will signal the library to stop iterating.
.P
Returns 0 if iteration completed successfully, 1 if the iteration was
terminated early, and -1 if there was an error.
.P
.B uint32_t ApeTag_size(struct ApeTag *tag);
.P
Returns the current size of the tag in the file, if a tag exists.
.BR ApeTag_exists
should be called before calling this method.
Note this does not reflect the size of the tag that will be written to file
if you've modified the tag's items.
This also does not include the size of the any ID3v1 tag.
.P
.B uint32_t ApeTag_item_count(struct ApeTag *tag);
.P
Returns the current number of items in the tag.
.BR ApeTag_exists
should be called before calling this method unless you are going to be
replacing the tag completely.
This reflects the count after items have been added or removed using
.BR ApeTag_add_item
and
.BR ApeTag_remove_item .
.P
.B uint32_t ApeTag_file_item_count(struct ApeTag *tag);
.P
Returns the current number of items in the tag in the file.
.BR ApeTag_exists
should be called before calling this method.
This does not reflect changes made by adding or removing items.
.P
.B enum ApeTag_errcode ApeTag_error_code(struct ApeTag *tag);
.P
Returns a member of ApeTag_errcode indicating the general area of the
cause of the last error.
More detail about the error can be found in the error message returned by
.BR ApeTag_error .
.P
.B const char * ApeTag_error(struct ApeTag *tag);
.P
Returns a pointer to the last error message.
This pointer should not be freed by the user.
.P
.B size_t ApeTag_get_max_size(void);
.P
Get the maximum tag size that this library will handle.
Tags larger than this will not be read or written.
Defaults to a very strict 8192 bytes, as recommended by
the APE specification.
.P
.B size_t ApeTag_get_max_item_count(void);
.P
Get the maximum number of items allowed in a tag.
Tags with more items than this will not be read or written.
Defaults to 64.
.P
.B void ApeTag_set_max_size(uint32_t size);
.P
Override the maximum tag size that this library will handle.
.P
.B void ApeTag_set_max_item_count(uint32_t item_count);
.P
Override the maximum number of items allowed in a tag.
.P
.B int ApeTag_mt_init(void);
.P
Should only be necessary in multi-threaded code.
If libapetag is used in multi-threaded code, should be called before
threads are created to initialize some global state.
If this function is called before creating threads, then libapetag
is thread-safe assuming you do not have multiple threads operating
on the same ApeTag or ApeItem struct concurrently.
.P
Returns 0 on success, -1 on error.
.SH AUTHOR
.B apetag
is written by Jeremy Evans. You can contact the author at
code@jeremyevans.net, and suggestions or bug reports are welcome.
.SH SEE ALSO
apeinfo(1), malloc(3), ferror(3)