C bindings for complex properties like pictures (#953)

Provides a unified API for complex properties in the same way as
the Properties API in the C bindings. Since constructing and
traversing complex properties in C is a bit complicated, there
are convenience functions for the most common use case of getting
or setting a single picture.

    TAGLIB_COMPLEX_PROPERTY_PICTURE(props, data, size, "Written by TagLib",
                                   "image/jpeg", "Front Cover");
    taglib_complex_property_set(file, "PICTURE", props);

and

    TagLib_Complex_Property_Attribute*** properties =
      taglib_complex_property_get(file, "PICTURE");
    TagLib_Complex_Property_Picture_Data picture;
    taglib_picture_from_complex_property(properties, &picture);
This commit is contained in:
Urs Fleisch 2023-10-15 19:38:15 +02:00
parent 1d213b8b98
commit a3ad2d0aaa
3 changed files with 619 additions and 2 deletions

View File

@ -23,11 +23,14 @@
#include <cstdlib>
#include <cstring>
#include <sstream>
#include <utility>
#ifdef HAVE_CONFIG_H
# include "config.h"
#endif
#include "tstringlist.h"
#include "tbytevectorlist.h"
#include "tfile.h"
#include "tpropertymap.h"
#include "fileref.h"
@ -412,7 +415,320 @@ void taglib_property_free(char **props)
char **p = props;
while(*p) {
free(*p++);
free(*p++);
}
free(props);
}
/******************************************************************************
* Complex Properties API
******************************************************************************/
namespace {
bool _taglib_complex_property_set(
TagLib_File *file, const char *key,
const TagLib_Complex_Property_Attribute **value, bool append)
{
if(file == NULL || key == NULL)
return false;
auto tfile = reinterpret_cast<File *>(file);
if(value == NULL) {
return tfile->setComplexProperties(key, {});
}
VariantMap map;
const TagLib_Complex_Property_Attribute** attrPtr = value;
while(*attrPtr) {
const TagLib_Complex_Property_Attribute *attr = *attrPtr;
String attrKey(attr->key);
TagLib_Variant_Type type = attr->value.type;
switch(type) {
case TagLib_Variant_Void:
map.insert(attrKey, Variant());
break;
case TagLib_Variant_Bool:
map.insert(attrKey, attr->value.value.boolValue != 0);
break;
case TagLib_Variant_Int:
map.insert(attrKey, attr->value.value.intValue);
break;
case TagLib_Variant_UInt:
map.insert(attrKey, attr->value.value.uIntValue);
break;
case TagLib_Variant_LongLong:
map.insert(attrKey, attr->value.value.longLongValue);
break;
case TagLib_Variant_ULongLong:
map.insert(attrKey, attr->value.value.uLongLongValue);
break;
case TagLib_Variant_Double:
map.insert(attrKey, attr->value.value.doubleValue);
break;
case TagLib_Variant_String:
map.insert(attrKey, attr->value.value.stringValue);
break;
case TagLib_Variant_StringList: {
StringList strs;
if(attr->value.value.stringListValue) {
char **s = attr->value.value.stringListValue;;
while(*s) {
strs.append(*s++);
}
}
map.insert(attrKey, strs);
break;
}
case TagLib_Variant_ByteVector:
map.insert(attrKey, ByteVector(attr->value.value.byteVectorValue,
attr->value.size));
break;
}
++attrPtr;
}
return append ? tfile->setComplexProperties(key, tfile->complexProperties(key).append(map))
: tfile->setComplexProperties(key, {map});
}
} // namespace
BOOL taglib_complex_property_set(
TagLib_File *file, const char *key,
const TagLib_Complex_Property_Attribute **value)
{
return _taglib_complex_property_set(file, key, value, false);
}
BOOL taglib_complex_property_set_append(
TagLib_File *file, const char *key,
const TagLib_Complex_Property_Attribute **value)
{
return _taglib_complex_property_set(file, key, value, true);
}
char** taglib_complex_property_keys(TagLib_File *file)
{
if(file == NULL) {
return NULL;
}
const StringList strs = reinterpret_cast<const File *>(file)->complexPropertyKeys();
if(strs.isEmpty()) {
return NULL;
}
auto keys = static_cast<char **>(malloc(sizeof(char *) * (strs.size() + 1)));
char **keyPtr = keys;
for(const auto &str : strs) {
*keyPtr++ = stringToCharArray(str);
}
*keyPtr = NULL;
return keys;
}
TagLib_Complex_Property_Attribute*** taglib_complex_property_get(
TagLib_File *file, const char *key)
{
if(file == NULL || key == NULL) {
return NULL;
}
const auto variantMaps = reinterpret_cast<const File *>(file)->complexProperties(key);
if(variantMaps.isEmpty()) {
return NULL;
}
TagLib_Complex_Property_Attribute ***props = static_cast<TagLib_Complex_Property_Attribute ***>(
malloc(sizeof(TagLib_Complex_Property_Attribute **) * (variantMaps.size() + 1)));
TagLib_Complex_Property_Attribute ***propPtr = props;
for(const auto &variantMap : variantMaps) {
TagLib_Complex_Property_Attribute **attrs = static_cast<TagLib_Complex_Property_Attribute **>(
malloc(sizeof(TagLib_Complex_Property_Attribute *) * (variantMap.size() + 1)));
TagLib_Complex_Property_Attribute *attr = static_cast<TagLib_Complex_Property_Attribute *>(
malloc(sizeof(TagLib_Complex_Property_Attribute) * variantMap.size()));
TagLib_Complex_Property_Attribute **attrPtr = attrs;
for (const auto &[k, v] : variantMap) {
attr->key = stringToCharArray(k);
attr->value.size = 0;
switch(v.type()) {
case Variant::Void:
attr->value.type = TagLib_Variant_Void;
attr->value.value.stringValue = NULL;
break;
case Variant::Bool:
attr->value.type = TagLib_Variant_Bool;
attr->value.value.boolValue = v.value<bool>();
break;
case Variant::Int:
attr->value.type = TagLib_Variant_Int;
attr->value.value.intValue = v.value<int>();
break;
case Variant::UInt:
attr->value.type = TagLib_Variant_UInt;
attr->value.value.uIntValue = v.value<unsigned int>();
break;
case Variant::LongLong:
attr->value.type = TagLib_Variant_LongLong;
attr->value.value.longLongValue = v.value<long long>();
break;
case Variant::ULongLong:
attr->value.type = TagLib_Variant_ULongLong;
attr->value.value.uLongLongValue = v.value<unsigned long long>();
break;
case Variant::Double:
attr->value.type = TagLib_Variant_Double;
attr->value.value.doubleValue = v.value<double>();
break;
case Variant::String: {
attr->value.type = TagLib_Variant_String;
auto str = v.value<String>();
attr->value.value.stringValue = stringToCharArray(str);
attr->value.size = str.size();
break;
}
case Variant::StringList: {
attr->value.type = TagLib_Variant_StringList;
StringList strs = v.value<StringList>();
auto strPtr = static_cast<char **>(malloc(sizeof(char *) * (strs.size() + 1)));
attr->value.value.stringListValue = strPtr;
attr->value.size = strs.size();
for(const auto &str : strs) {
*strPtr++ = stringToCharArray(str);
}
*strPtr = NULL;
break;
}
case Variant::ByteVector: {
attr->value.type = TagLib_Variant_ByteVector;
const ByteVector data = v.value<ByteVector>();
auto bytePtr = static_cast<char *>(malloc(data.size()));
attr->value.value.byteVectorValue = bytePtr;
attr->value.size = data.size();
::memcpy(bytePtr, data.data(), data.size());
break;
}
case Variant::ByteVectorList:
case Variant::VariantList:
case Variant::VariantMap: {
attr->value.type = TagLib_Variant_String;
std::stringstream ss;
ss << v;
attr->value.value.stringValue = stringToCharArray(ss.str());
break;
}
}
*attrPtr++ = attr++;
}
*attrPtr++ = NULL;
*propPtr++ = attrs;
}
*propPtr = NULL;
return props;
}
void taglib_picture_from_complex_property(
TagLib_Complex_Property_Attribute*** properties,
TagLib_Complex_Property_Picture_Data *picture)
{
if(!properties || !picture) {
return;
}
std::memset(picture, 0, sizeof(*picture));
TagLib_Complex_Property_Attribute*** propPtr = properties;
while(!picture->data && *propPtr) {
TagLib_Complex_Property_Attribute** attrPtr = *propPtr;
while(*attrPtr) {
TagLib_Complex_Property_Attribute *attr = *attrPtr;
TagLib_Variant_Type type = attr->value.type;
switch(type) {
case TagLib_Variant_String:
if(strcmp("mimeType", attr->key) == 0) {
picture->mimeType = attr->value.value.stringValue;
}
else if(strcmp("description", attr->key) == 0) {
picture->description = attr->value.value.stringValue;
}
else if(strcmp("pictureType", attr->key) == 0) {
picture->pictureType = attr->value.value.stringValue;
}
break;
case TagLib_Variant_ByteVector:
if(strcmp("data", attr->key) == 0) {
picture->data = attr->value.value.byteVectorValue;
picture->size = attr->value.size;
}
break;
default:
break;
}
++attrPtr;
}
++propPtr;
}
}
void taglib_complex_property_free_keys(char **keys)
{
if(keys == NULL) {
return;
}
char **k = keys;
while(*k) {
free(*k++);
}
free(keys);
}
void taglib_complex_property_free(
TagLib_Complex_Property_Attribute ***props)
{
if(props == NULL) {
return;
}
TagLib_Complex_Property_Attribute*** propPtr = props;
while(*propPtr) {
TagLib_Complex_Property_Attribute** attrPtr = *propPtr;
while(*attrPtr) {
TagLib_Complex_Property_Attribute *attr = *attrPtr;
TagLib_Variant_Type type = attr->value.type;
switch(type) {
case TagLib_Variant_String:
free(attr->value.value.stringValue);
break;
case TagLib_Variant_StringList:
if(attr->value.value.stringListValue) {
char **s = attr->value.value.stringListValue;
while(*s) {
free(*s++);
}
free(attr->value.value.stringListValue);
}
break;
case TagLib_Variant_ByteVector:
free(attr->value.value.byteVectorValue);
break;
case TagLib_Variant_Void:
case TagLib_Variant_Bool:
case TagLib_Variant_Int:
case TagLib_Variant_UInt:
case TagLib_Variant_LongLong:
case TagLib_Variant_ULongLong:
case TagLib_Variant_Double:
break;
}
free(attr->key);
++attrPtr;
}
free(**propPtr);
free(*propPtr++);
}
free(props);
}

View File

@ -320,7 +320,7 @@ TAGLIB_C_EXPORT char** taglib_property_keys(TagLib_File *file);
* Get value(s) of property \a prop.
*
* \return NULL terminated array of C-strings (char *), only NULL if empty.
It must be freed by the client using taglib_property_free().
* It must be freed by the client using taglib_property_free().
*/
TAGLIB_C_EXPORT char** taglib_property_get(TagLib_File *file, const char *prop);
@ -329,6 +329,238 @@ TAGLIB_C_EXPORT char** taglib_property_get(TagLib_File *file, const char *prop);
*/
TAGLIB_C_EXPORT void taglib_property_free(char **props);
/******************************************************************************
* Complex Properties API
******************************************************************************/
/*!
* Types which can be stored in a TagLib_Variant.
*
* \related TagLib::Variant::Type
* These correspond to TagLib::Variant::Type, but ByteVectorList, VariantList,
* VariantMap are not supported and will be returned as their string
* representation.
*/
typedef enum {
TagLib_Variant_Void,
TagLib_Variant_Bool,
TagLib_Variant_Int,
TagLib_Variant_UInt,
TagLib_Variant_LongLong,
TagLib_Variant_ULongLong,
TagLib_Variant_Double,
TagLib_Variant_String,
TagLib_Variant_StringList,
TagLib_Variant_ByteVector
} TagLib_Variant_Type;
/*!
* Discriminated union used in complex property attributes.
*
* \e type must be set according to the \e value union used.
* \e size is only required for TagLib_Variant_ByteVector and must contain
* the number of bytes.
*
* \related TagLib::Variant.
*/
typedef struct {
TagLib_Variant_Type type;
unsigned int size;
union {
char *stringValue;
char *byteVectorValue;
char **stringListValue;
BOOL boolValue;
int intValue;
unsigned int uIntValue;
long long longLongValue;
unsigned long long uLongLongValue;
double doubleValue;
} value;
} TagLib_Variant;
/*!
* Attribute of a complex property.
* Complex properties consist of a NULL-terminated array of pointers to
* this structure with \e key and \e value.
*/
typedef struct {
char *key;
TagLib_Variant value;
} TagLib_Complex_Property_Attribute;
/*!
* Picture data extracted from a complex property by the convenience function
* taglib_picture_from_complex_property().
*/
typedef struct {
char *mimeType;
char *description;
char *pictureType;
char *data;
unsigned int size;
} TagLib_Complex_Property_Picture_Data;
/*!
* Declare complex property attributes to set a picture.
* Can be used to define a variable \a var which can be used with
* taglib_complex_property_set() and a "PICTURE" key to set an
* embedded picture with the picture data \a dat of size \a siz
* and description \a desc, mime type \a mime and picture type
* \a typ (size is unsigned int, the other input parameters char *).
*/
#define TAGLIB_COMPLEX_PROPERTY_PICTURE(var, dat, siz, desc, mime, typ) \
const TagLib_Complex_Property_Attribute \
var##Attrs[] = { \
{ \
(char *)"data", \
{ \
TagLib_Variant_ByteVector, \
(siz), \
{ \
(char *)(dat) \
} \
} \
}, \
{ \
(char *)"mimeType", \
{ \
TagLib_Variant_String, \
0U, \
{ \
(char *)(mime) \
} \
} \
}, \
{ \
(char *)"description", \
{ \
TagLib_Variant_String, \
0U, \
{ \
(char *)(desc) \
} \
} \
}, \
{ \
(char *)"pictureType", \
{ \
TagLib_Variant_String, \
0U, \
{ \
(char *)(typ) \
} \
} \
} \
}; \
const TagLib_Complex_Property_Attribute *var[] = { \
&var##Attrs[0], &var##Attrs[1], &var##Attrs[2], \
&var##Attrs[3], NULL \
}
/*!
* Sets the complex property \a key with \a value. Use \a value = NULL to
* remove the property, otherwise it will be replaced with the NULL
* terminated array of attributes in \a value.
*
* A picture can be set with the TAGLIB_COMPLEX_PROPERTY_PICTURE macro:
*
* \code {.c}
* TagLib_File *file = taglib_file_new("myfile.mp3");
* FILE *fh = fopen("mypicture.jpg", "rb");
* if(fh) {
* fseek(fh, 0L, SEEK_END);
* long size = ftell(fh);
* fseek(fh, 0L, SEEK_SET);
* char *data = (char *)malloc(size);
* fread(data, size, 1, fh);
* TAGLIB_COMPLEX_PROPERTY_PICTURE(props, data, size, "Written by TagLib",
* "image/jpeg", "Front Cover");
* taglib_complex_property_set(file, "PICTURE", props);
* taglib_file_save(file);
* free(data);
* fclose(fh);
* }
* \endcode
*/
TAGLIB_C_EXPORT BOOL taglib_complex_property_set(
TagLib_File *file, const char *key,
const TagLib_Complex_Property_Attribute **value);
/*!
* Appends \a value to the complex property \a key (sets it if non-existing).
* Use \a value = NULL to remove all values associated with the \a key.
*/
TAGLIB_C_EXPORT BOOL taglib_complex_property_set_append(
TagLib_File *file, const char *key,
const TagLib_Complex_Property_Attribute **value);
/*!
* Get the keys of the complex properties.
*
* \return NULL terminated array of C-strings (char *), only NULL if empty.
* It must be freed by the client using taglib_complex_property_free_keys().
*/
TAGLIB_C_EXPORT char** taglib_complex_property_keys(TagLib_File *file);
/*!
* Get value(s) of complex property \a key.
*
* \return NULL terminated array of property values, which are themselves an
* array of property attributes, only NULL if empty.
* It must be freed by the client using taglib_complex_property_free().
*/
TAGLIB_C_EXPORT TagLib_Complex_Property_Attribute*** taglib_complex_property_get(
TagLib_File *file, const char *key);
/*!
* Extract the complex property values of a picture.
*
* This function can be used to get the data from a "PICTURE" complex property
* without having to traverse the whole variant map. A picture can be
* retrieved like this:
*
* \code {.c}
* TagLib_File *file = taglib_file_new("myfile.mp3");
* TagLib_Complex_Property_Attribute*** properties =
* taglib_complex_property_get(file, "PICTURE");
* TagLib_Complex_Property_Picture_Data picture;
* taglib_picture_from_complex_property(properties, &picture);
* // Do something with picture.mimeType, picture.description,
* // picture.pictureType, picture.data, picture.size, e.g. extract it.
* FILE *fh = fopen("mypicture.jpg", "wb");
* if(fh) {
* fwrite(picture.data, picture.size, 1, fh);
* fclose(fh);
* }
* taglib_complex_property_free(properties);
* \endcode
*
* Note that the data in \a picture contains pointers to data in \a properties,
* i.e. it only lives as long as the properties, until they are freed with
* taglib_complex_property_free().
* If you want to access multiple pictures or additional properties of FLAC
* pictures ("width", "height", "numColors", "colorDepth" int values), you
* have to traverse the \a properties yourself.
*/
TAGLIB_C_EXPORT void taglib_picture_from_complex_property(
TagLib_Complex_Property_Attribute*** properties,
TagLib_Complex_Property_Picture_Data *picture);
/*!
* Frees the NULL terminated array \a keys (as returned by
* taglib_complex_property_keys()) and the C-strings it contains.
*/
TAGLIB_C_EXPORT void taglib_complex_property_free_keys(char **keys);
/*!
* Frees the NULL terminated array \a props of property attribute arrays
* (as returned by taglib_complex_property_get()) and the data such as
* C-strings and byte vectors contained in these attributes.
*/
TAGLIB_C_EXPORT void taglib_complex_property_free(
TagLib_Complex_Property_Attribute ***props);
#ifdef __cplusplus
}
#endif

View File

@ -40,6 +40,7 @@ int main(int argc, char *argv[])
TagLib_Tag *tag;
const TagLib_AudioProperties *properties;
char **propertiesMap;
char **complexKeys;
taglib_set_strings_unicode(1);
@ -54,6 +55,7 @@ int main(int argc, char *argv[])
tag = taglib_file_tag(file);
properties = taglib_file_audioproperties(file);
propertiesMap = taglib_property_keys(file);
complexKeys = taglib_complex_property_keys(file);
if(tag != NULL) {
printf("-- TAG (basic) --\n");
@ -91,6 +93,73 @@ int main(int argc, char *argv[])
}
}
if(complexKeys != NULL) {
char **keyPtr = complexKeys;
while(*keyPtr) {
TagLib_Complex_Property_Attribute*** properties =
taglib_complex_property_get(file, *keyPtr);
printf("%s:\n", *keyPtr);
if(properties != NULL) {
TagLib_Complex_Property_Attribute*** propPtr = properties;
while(*propPtr) {
TagLib_Complex_Property_Attribute** attrPtr = *propPtr;
while(*attrPtr) {
TagLib_Complex_Property_Attribute *attr = *attrPtr;
TagLib_Variant_Type type = attr->value.type;
printf(" %-11s - ", attr->key);
switch(type) {
case TagLib_Variant_Void:
printf("null\n");
break;
case TagLib_Variant_Bool:
printf("%s\n", attr->value.value.boolValue ? "true" : "false");
break;
case TagLib_Variant_Int:
printf("%d\n", attr->value.value.intValue);
break;
case TagLib_Variant_UInt:
printf("%u\n", attr->value.value.uIntValue);
break;
case TagLib_Variant_LongLong:
printf("%lld\n", attr->value.value.longLongValue);
break;
case TagLib_Variant_ULongLong:
printf("%llu\n", attr->value.value.uLongLongValue);
break;
case TagLib_Variant_Double:
printf("%f\n", attr->value.value.doubleValue);
break;
case TagLib_Variant_String:
printf("%s\n", attr->value.value.stringValue);
break;
case TagLib_Variant_StringList:
if(attr->value.value.stringListValue) {
char **strs = attr->value.value.stringListValue;
char **s = strs;
while(*s) {
if(s != strs) {
printf(" ");
}
printf("%s", *s++);
}
}
printf("\n");
break;
case TagLib_Variant_ByteVector:
printf("(%u bytes)\n", attr->value.size);
break;
}
++attrPtr;
}
++propPtr;
}
taglib_complex_property_free(properties);
}
++keyPtr;
}
taglib_complex_property_free_keys(complexKeys);
}
if(properties != NULL) {
seconds = taglib_audioproperties_length(properties) % 60;
minutes = (taglib_audioproperties_length(properties) - seconds) / 60;