mpg123 metadata handling

Collaboration diagram for mpg123 metadata handling:

Modules
	mpg123 advanced parameter API

Classes
struct	mpg123_string
struct	mpg123_text
struct	mpg123_picture
struct	mpg123_id3v2
struct	mpg123_id3v1

Macros
#define	MPG123_ID3   0x3
#define	MPG123_NEW_ID3   0x1
#define	MPG123_ICY   0xc
#define	MPG123_NEW_ICY   0x4

Enumerations
enum	mpg123_text_encoding {   mpg123_text_unknown = 0 , mpg123_text_utf8 = 1 , mpg123_text_latin1 = 2 , mpg123_text_icy = 3 ,   mpg123_text_cp1252 = 4 , mpg123_text_utf16 = 5 , mpg123_text_utf16bom = 6 , mpg123_text_utf16be = 7 ,   mpg123_text_max = 7 }
enum	mpg123_id3_enc {   mpg123_id3_latin1 = 0 , mpg123_id3_utf16bom = 1 , mpg123_id3_utf16be = 2 , mpg123_id3_utf8 = 3 ,   mpg123_id3_enc_max = 3 }
enum	mpg123_id3_pic_type {   mpg123_id3_pic_other = 0 , mpg123_id3_pic_icon = 1 , mpg123_id3_pic_other_icon = 2 , mpg123_id3_pic_front_cover = 3 ,   mpg123_id3_pic_back_cover = 4 , mpg123_id3_pic_leaflet = 5 , mpg123_id3_pic_media = 6 , mpg123_id3_pic_lead = 7 ,   mpg123_id3_pic_artist = 8 , mpg123_id3_pic_conductor = 9 , mpg123_id3_pic_orchestra = 10 , mpg123_id3_pic_composer = 11 ,   mpg123_id3_pic_lyricist = 12 , mpg123_id3_pic_location = 13 , mpg123_id3_pic_recording = 14 , mpg123_id3_pic_performance = 15 ,   mpg123_id3_pic_video = 16 , mpg123_id3_pic_fish = 17 , mpg123_id3_pic_illustration = 18 , mpg123_id3_pic_artist_logo = 19 ,   mpg123_id3_pic_publisher_logo = 20 }

Functions
MPG123_EXPORT mpg123_string *	mpg123_new_string (const char *val)
MPG123_EXPORT void	mpg123_delete_string (mpg123_string *sb)
MPG123_EXPORT void	mpg123_init_string (mpg123_string *sb)
MPG123_EXPORT void	mpg123_free_string (mpg123_string *sb)
MPG123_EXPORT int	mpg123_resize_string (mpg123_string *sb, size_t news)
MPG123_EXPORT int	mpg123_grow_string (mpg123_string *sb, size_t news)
MPG123_EXPORT int	mpg123_copy_string (mpg123_string *from, mpg123_string *to)
MPG123_EXPORT int	mpg123_move_string (mpg123_string *from, mpg123_string *to)
MPG123_EXPORT int	mpg123_add_string (mpg123_string *sb, const char *stuff)
MPG123_EXPORT int	mpg123_add_substring (mpg123_string *sb, const char *stuff, size_t from, size_t count)
MPG123_EXPORT int	mpg123_set_string (mpg123_string *sb, const char *stuff)
MPG123_EXPORT int	mpg123_set_substring (mpg123_string *sb, const char *stuff, size_t from, size_t count)
MPG123_EXPORT size_t	mpg123_strlen (mpg123_string *sb, int utf8)
MPG123_EXPORT int	mpg123_chomp_string (mpg123_string *sb)
MPG123_EXPORT int	mpg123_same_string (mpg123_string *a, mpg123_string *b)
MPG123_EXPORT enum mpg123_text_encoding	mpg123_enc_from_id3 (unsigned char id3_enc_byte)
MPG123_EXPORT int	mpg123_store_utf8 (mpg123_string *sb, enum mpg123_text_encoding enc, const unsigned char *source, size_t source_size)
MPG123_EXPORT int	mpg123_meta_check (mpg123_handle *mh)
MPG123_EXPORT void	mpg123_meta_free (mpg123_handle *mh)
MPG123_EXPORT int	mpg123_id3 (mpg123_handle *mh, mpg123_id3v1 **v1, mpg123_id3v2 **v2)
MPG123_EXPORT int	mpg123_id3_raw (mpg123_handle *mh, unsigned char **v1, size_t *v1_size, unsigned char **v2, size_t *v2_size)
MPG123_EXPORT int	mpg123_icy (mpg123_handle *mh, char **icy_meta)
MPG123_EXPORT char *	mpg123_icy2utf8 (const char *icy_text)

Detailed Description

Functions to retrieve the metadata from MPEG Audio files and streams. Also includes string handling functions.

Macro Definition Documentation

MPG123_ICY

#define MPG123_ICY   0xc

1100 There is some ICY info. Also matches 0100 or NEW_ICY.

Definition at line 1466 of file mpg123.h.

MPG123_ID3

#define MPG123_ID3   0x3

0011 There is some ID3 info. Also matches 0010 or NEW_ID3.

Definition at line 1464 of file mpg123.h.

MPG123_NEW_ICY

#define MPG123_NEW_ICY   0x4

0100 There is ICY info that changed since last call to mpg123_icy.

Definition at line 1467 of file mpg123.h.

MPG123_NEW_ID3

#define MPG123_NEW_ID3   0x1

0001 There is ID3 info that changed since last call to mpg123_id3.

Definition at line 1465 of file mpg123.h.

Enumeration Type Documentation

mpg123_id3_enc

enum mpg123_id3_enc

The encoding byte values from ID3v2.

Enumerator
mpg123_id3_latin1	Note: This sometimes can mean anything in practice...
mpg123_id3_utf16bom	UTF16, UCS-2 ... it's all the same for practical purposes.
mpg123_id3_utf16be	Big-endian UTF-16, BOM see note for mpg123_text_utf16be.
mpg123_id3_utf8	Our lovely overly ASCII-compatible 8 byte encoding for the world.
mpg123_id3_enc_max	Placeholder to check valid range of encoding byte.

Definition at line 1342 of file mpg123.h.

{
     mpg123_id3_latin1   = 0 
    ,mpg123_id3_utf16bom = 1 
    ,mpg123_id3_utf16be  = 2 
    ,mpg123_id3_utf8     = 3 
    ,mpg123_id3_enc_max  = 3 
};

mpg123_id3_pic_type

enum mpg123_id3_pic_type

The picture type values from ID3v2.

Enumerator
mpg123_id3_pic_other	see ID3v2 docs
mpg123_id3_pic_icon	see ID3v2 docs
mpg123_id3_pic_other_icon	see ID3v2 docs
mpg123_id3_pic_front_cover	see ID3v2 docs
mpg123_id3_pic_back_cover	see ID3v2 docs
mpg123_id3_pic_leaflet	see ID3v2 docs
mpg123_id3_pic_media	see ID3v2 docs
mpg123_id3_pic_lead	see ID3v2 docs
mpg123_id3_pic_artist	see ID3v2 docs
mpg123_id3_pic_conductor	see ID3v2 docs
mpg123_id3_pic_orchestra	see ID3v2 docs
mpg123_id3_pic_composer	see ID3v2 docs
mpg123_id3_pic_lyricist	see ID3v2 docs
mpg123_id3_pic_location	see ID3v2 docs
mpg123_id3_pic_recording	see ID3v2 docs
mpg123_id3_pic_performance	see ID3v2 docs
mpg123_id3_pic_video	see ID3v2 docs
mpg123_id3_pic_fish	see ID3v2 docs
mpg123_id3_pic_illustration	see ID3v2 docs
mpg123_id3_pic_artist_logo	see ID3v2 docs
mpg123_id3_pic_publisher_logo	see ID3v2 docs

Definition at line 1384 of file mpg123.h.

{
     mpg123_id3_pic_other          =  0 
    ,mpg123_id3_pic_icon           =  1 
    ,mpg123_id3_pic_other_icon     =  2 
    ,mpg123_id3_pic_front_cover    =  3 
    ,mpg123_id3_pic_back_cover     =  4 
    ,mpg123_id3_pic_leaflet        =  5 
    ,mpg123_id3_pic_media          =  6 
    ,mpg123_id3_pic_lead           =  7 
    ,mpg123_id3_pic_artist         =  8 
    ,mpg123_id3_pic_conductor      =  9 
    ,mpg123_id3_pic_orchestra      = 10 
    ,mpg123_id3_pic_composer       = 11 
    ,mpg123_id3_pic_lyricist       = 12 
    ,mpg123_id3_pic_location       = 13 
    ,mpg123_id3_pic_recording      = 14 
    ,mpg123_id3_pic_performance    = 15 
    ,mpg123_id3_pic_video          = 16 
    ,mpg123_id3_pic_fish           = 17 
    ,mpg123_id3_pic_illustration   = 18 
    ,mpg123_id3_pic_artist_logo    = 19 
    ,mpg123_id3_pic_publisher_logo = 20 
};

mpg123_text_encoding

enum mpg123_text_encoding

The mpg123 text encodings. This contains encodings we encounter in ID3 tags or ICY meta info.

Enumerator
mpg123_text_unknown	Unkown encoding... mpg123_id3_encoding can return that on invalid codes.
mpg123_text_utf8	UTF-8
mpg123_text_latin1	ISO-8859-1. Note that sometimes latin1 in ID3 is abused for totally different encodings.
mpg123_text_icy	ICY metadata encoding, usually CP-1252 but we take it as UTF-8 if it qualifies as such.
mpg123_text_cp1252	Really CP-1252 without any guessing.
mpg123_text_utf16	Some UTF-16 encoding. The last of a set of leading BOMs (byte order mark) rules. When there is no BOM, big endian ordering is used. Note that UCS-2 qualifies as UTF-8 when you don't mess with the reserved code points. If you want to decode little endian data without BOM you need to prepend 0xff 0xfe yourself.
mpg123_text_utf16bom	Just an alias for UTF-16, ID3v2 has this as distinct code.
mpg123_text_utf16be	Another alias for UTF16 from ID3v2. Note, that, because of the mess that is reality, BOMs are used if encountered. There really is not much distinction between the UTF16 types for mpg123 One exception: Since this is seen in ID3v2 tags, leading null bytes are skipped for all other UTF16 types (we expect a BOM before real data there), not so for utf16be!
mpg123_text_max	Placeholder for the maximum encoding value.

Definition at line 1322 of file mpg123.h.

{
     mpg123_text_unknown  = 0 
    ,mpg123_text_utf8     = 1 
    ,mpg123_text_latin1   = 2 
    ,mpg123_text_icy      = 3 
    ,mpg123_text_cp1252   = 4 
    ,mpg123_text_utf16    = 5 
    ,mpg123_text_utf16bom = 6 
    ,mpg123_text_utf16be  = 7 
    ,mpg123_text_max      = 7 
};

Function Documentation

mpg123_add_string()

MPG123_EXPORT int mpg123_add_string	(	mpg123_string *	sb,
		const char *	stuff
	)

Append a C-String to an mpg123_string

Parameters

sb	string handle
stuff	to append

Returns

0 on error, 1 on success

Definition at line 135 of file stringbuf.c.

{
    debug1("adding %s", stuff);
    return mpg123_add_substring(sb, stuff, 0, stuff ? strlen(stuff) : 0);
}

Referenced by mpg123_set_string().

mpg123_add_substring()

MPG123_EXPORT int mpg123_add_substring	(	mpg123_string *	sb,
		const char *	stuff,
		size_t	from,
		size_t	count
	)

Append a C-substring to an mpg123 string

Parameters

sb	string handle
stuff	content to copy
from	offset to copy from
count	number of characters to copy (a null-byte is always appended)

Returns

0 on error, 1 on success

Definition at line 141 of file stringbuf.c.

{
    debug("adding a substring");
    if(!sb || !stuff)
        return 0;
    if(sb->fill) /* includes zero byte... */
    {
        if( (SIZE_MAX - sb->fill >= count) /* Avoid overflow. */
            && (sb->size >= sb->fill+count || mpg123_grow_string(sb, sb->fill+count)) )
        {
            memcpy(sb->p+sb->fill-1, stuff+from, count);
            sb->fill += count;
            sb->p[sb->fill-1] = 0; /* Terminate! */
        }
        else return 0;
    }
    else
    {
        if( count < SIZE_MAX && mpg123_grow_string(sb, count+1) )
        {
            memcpy(sb->p, stuff+from, count);
            sb->fill = count+1;
            sb->p[sb->fill-1] = 0; /* Terminate! */
        }
        else return 0;
    }
    return 1;
}

Referenced by mpg123_add_string(), and mpg123_set_substring().

mpg123_chomp_string()

MPG123_EXPORT int mpg123_chomp_string

(

mpg123_string *

sb

)

Remove trailing \r and \n, if present.

Parameters

sb	string handle

Returns

0 on error, 1 on success

Definition at line 218 of file stringbuf.c.

{
    ssize_t i;
    if(!sb || !sb->fill) return 0;
 
    /* Ensure that it is zero-terminated. */
    sb->p[sb->fill-1] = 0;
    for(i=sb->fill-2; i>=0; --i)
    {
        char *c = sb->p+i;
        /* Stop at the first proper character. */
        if(*c && *c != '\r' && *c != '\n') break;
        else *c = 0;
    }
    /* initial fill at least 1, so i at least -1,
       +2 means nothing happened for fill=1 .
       With i=0, we got one non-null character, fill shall be 2
       to accomodate the trailing zero. */
    sb->fill = (size_t)i+2;
 
    return 1;
}

mpg123_copy_string()

MPG123_EXPORT int mpg123_copy_string	(	mpg123_string *	from,
		mpg123_string *	to
	)

Copy the contents of one mpg123_string string to another. Yes the order of arguments is reversed compated to memcpy().

Parameters

from	string handle
to	string handle

Returns

0 on error, 1 on success

Definition at line 93 of file stringbuf.c.

{
    size_t fill;
    char  *text;
 
    debug2("called copy_string with %p -> %p", (void*)from, (void*)to);
    if(to == NULL)
        return 0;
    if(from == NULL)
    {
        fill = 0;
        text = NULL;
    }
    else
    {
        fill = from->fill;
        text = from->p;
    }
 
    if(mpg123_resize_string(to, fill))
    {
        if(fill) /* Avoid memcpy(NULL, NULL, 0) */
            memcpy(to->p, text, fill);
        to->fill = fill;
        return 1;
    }
    else return 0;
}

mpg123_delete_string()

MPG123_EXPORT void mpg123_delete_string

(

mpg123_string *

sb

)

Free memory of contents and the string structure itself.

Parameters

sb	string handle

Definition at line 27 of file stringbuf.c.

{
    if(!sb)
        return;
    mpg123_free_string(sb);
    free(sb);
}

mpg123_enc_from_id3()

MPG123_EXPORT enum mpg123_text_encoding mpg123_enc_from_id3

(

unsigned char

id3_enc_byte

)

Convert ID3 encoding byte to mpg123 encoding index.

Parameters

id3_enc_byte

the ID3 encoding code

Returns

the mpg123 encoding index

Definition at line 1591 of file libmpg123.c.

{
    switch(id3_enc_byte)
    {
        case mpg123_id3_latin1:   return mpg123_text_latin1;
        case mpg123_id3_utf16bom: return mpg123_text_utf16bom; /* ID3v2.3 has UCS-2 with BOM here. */
        case mpg123_id3_utf16be:  return mpg123_text_utf16be;
        case mpg123_id3_utf8:     return mpg123_text_utf8;
        default: return mpg123_text_unknown;
    }
}

mpg123_free_string()

MPG123_EXPORT void mpg123_free_string

(

mpg123_string *

sb

)

Free-up memory of the contents of an mpg123_string (not the struct itself). This also calls mpg123_init_string() and hence is safe to be called repeatedly.

Parameters

sb	string handle

Definition at line 43 of file stringbuf.c.

{
    if(!sb)
        return;
    if(sb->p != NULL) free(sb->p);
    mpg123_init_string(sb);
}

Referenced by free_mpg123_picture(), free_mpg123_text(), mpg123_delete_string(), mpg123_move_string(), mpg123_store_utf8(), process_comment(), process_extra(), and process_picture().

mpg123_grow_string()

MPG123_EXPORT int mpg123_grow_string	(	mpg123_string *	sb,
		size_t	news
	)

Increase size of a mpg123_string if necessary (it may stay larger). Note that the functions for adding and setting in current libmpg123 use this instead of mpg123_resize_string(). That way, you can preallocate memory and safely work afterwards with pieces.

Parameters

sb	string handle
news	new minimum size

Returns

0 on error, 1 on success

Definition at line 51 of file stringbuf.c.

{
    if(!sb)
        return 0;
    if(sb->size < new) return mpg123_resize_string(sb, new);
    else return 1;
}

Referenced by convert_latin1(), convert_utf16bom(), convert_utf8(), mpg123_add_substring(), and store_id3_text().

mpg123_icy()

MPG123_EXPORT int mpg123_icy	(	mpg123_handle *	mh,
		char **	icy_meta
	)

Point icy_meta to existing data structure wich may change on any next read/decode function call.

Parameters

mh	handle
icy_meta	return address for ICY meta string (set to NULL if nothing there)

Returns

MPG123_OK on success

Definition at line 1557 of file libmpg123.c.

{
    if(mh == NULL) return MPG123_BAD_HANDLE;
#ifndef NO_ICY
    if(icy_meta == NULL)
    {
        mh->err = MPG123_NULL_POINTER;
        return MPG123_ERR;
    }
    *icy_meta = NULL;
 
    if(mh->metaflags & MPG123_ICY)
    {
        *icy_meta = mh->icy.data;
        mh->metaflags |= MPG123_ICY;
        mh->metaflags &= ~MPG123_NEW_ICY;
    }
    return MPG123_OK;
#else
    mh->err = MPG123_MISSING_FEATURE;
    return MPG123_ERR;
#endif
}

mpg123_icy2utf8()

MPG123_EXPORT char * mpg123_icy2utf8

(

const char *

icy_text

)

Decode from windows-1252 (the encoding ICY metainfo used) to UTF-8. Note that this is very similar to mpg123_store_utf8(&sb, mpg123_text_icy, icy_text, strlen(icy_text+1)) .

Parameters

icy_text

The input data in ICY encoding

Returns

pointer to newly allocated buffer with UTF-8 data (You free() it!)

Definition at line 1581 of file libmpg123.c.

{
#ifndef NO_ICY
    return icy2utf8(icy_text, 0);
#else
    return NULL;
#endif
}

mpg123_id3()

MPG123_EXPORT int mpg123_id3	(	mpg123_handle *	mh,
		mpg123_id3v1 **	v1,
		mpg123_id3v2 **	v2
	)

Point v1 and v2 to existing data structures wich may change on any next read/decode function call. v1 and/or v2 can be set to NULL when there is no corresponding data.

Returns

MPG123_OK on success

Definition at line 1517 of file libmpg123.c.

{
    if(v1 != NULL) *v1 = NULL;
    if(v2 != NULL) *v2 = NULL;
    if(mh == NULL) return MPG123_BAD_HANDLE;
 
    if(mh->metaflags & MPG123_ID3)
    {
        id3_link(mh);
        if(v1 != NULL && mh->rdat.flags & READER_ID3TAG) *v1 = (mpg123_id3v1*) mh->id3buf;
        if(v2 != NULL)
#ifdef NO_ID3V2
        *v2 = NULL;
#else
        *v2 = &mh->id3v2;
#endif
 
        mh->metaflags |= MPG123_ID3;
        mh->metaflags &= ~MPG123_NEW_ID3;
    }
    return MPG123_OK;
}

mpg123_id3_raw()

MPG123_EXPORT int mpg123_id3_raw	(	mpg123_handle *	mh,
		unsigned char **	v1,
		size_t *	v1_size,
		unsigned char **	v2,
		size_t *	v2_size
	)

Return pointers to and size of stored raw ID3 data if storage has been configured with MPG123_RAW_ID3 and stream parsing passed the metadata already. Null value with zero size is a possibility! The storage can change at any next API call.

Parameters

v1	address to store pointer to v1 tag
v1_size	size of v1 data in bytes
v2	address to store pointer to v2 tag
v2_size	size of v2 data in bytes

Returns

MPG123_OK or MPG123_ERR. Only on MPG123_OK the output values are set.

Definition at line 1540 of file libmpg123.c.

{
    if(!mh)
        return MPG123_ERR;
    if(v1 != NULL)
        *v1 = mh->id3buf[0] ? mh->id3buf : NULL;
    if(v1_size != NULL)
        *v1_size = mh->id3buf[0] ? 128 : 0;
    if(v2 != NULL)
        *v2 = mh->id3v2_raw;
    if(v2_size != NULL)
        *v2_size = mh->id3v2_size;
    return MPG123_OK;
}

mpg123_init_string()

MPG123_EXPORT void mpg123_init_string

(

mpg123_string *

sb

)

Initialize an existing mpg123_string structure to {NULL, 0, 0}. If you hand in a NULL pointer here, your program should crash. The other string functions are more forgiving, but this one here is too basic.

Parameters

sb	string handle (address of existing structure on your side)

Definition at line 35 of file stringbuf.c.

{
    /* Handing in NULL here is a fatal mistake and rightfully so. */
    sb->p = NULL;
    sb->size = 0;
    sb->fill = 0;
}

Referenced by init_mpg123_picture(), init_mpg123_text(), mpg123_free_string(), mpg123_move_string(), mpg123_new_string(), mpg123_resize_string(), process_comment(), process_extra(), and process_picture().

mpg123_meta_check()

MPG123_EXPORT int mpg123_meta_check

(

mpg123_handle *

mh

)

Query if there is (new) meta info, be it ID3 or ICY (or something new in future).

Parameters

mh

handle

Returns

combination of flags, 0 on error (same as "nothing new")

Definition at line 1503 of file libmpg123.c.

{
    if(mh != NULL) return mh->metaflags;
    else return 0;
}

mpg123_meta_free()

MPG123_EXPORT void mpg123_meta_free

(

mpg123_handle *

mh

)

Clean up meta data storage (ID3v2 and ICY), freeing memory.

Parameters

mh

handle

Definition at line 1509 of file libmpg123.c.

{
    if(mh == NULL) return;
 
    reset_id3(mh);
    reset_icy(&mh->icy);
}

mpg123_move_string()

MPG123_EXPORT int mpg123_move_string	(	mpg123_string *	from,
		mpg123_string *	to
	)

Move the contents of one mpg123_string string to another. This frees any memory associated with the target and moves over the pointers from the source, leaving the source without content after that. The only possible error is that you hand in NULL pointers. If you handed in a valid source, its contents will be gone, even if there was no target to move to. If you hand in a valid target, its original contents will also always be gone, to be replaced with the source's contents if there was some.

Parameters

from	source string handle
to	target string handle

Returns

0 on error, 1 on success

Definition at line 122 of file stringbuf.c.

{
    if(to)
        mpg123_free_string(to);
    else
        mpg123_free_string(from);
    if(from && to)
        *to = *from;
    if(from)
        mpg123_init_string(from);
    return (from && to) ? 1 : 0;
}

Referenced by process_comment(), process_extra(), and process_picture().

mpg123_new_string()

MPG123_EXPORT mpg123_string * mpg123_new_string

(

const char *

val

)

Allocate and intialize a new string.

Parameters

val	optional initial string value (can be NULL)

Definition at line 17 of file stringbuf.c.

{
    mpg123_string *sb = malloc(sizeof(mpg123_string));
    if(!sb)
        return NULL;
    mpg123_init_string(sb);
    mpg123_set_string(sb, val);
    return sb;
}

mpg123_resize_string()

MPG123_EXPORT int mpg123_resize_string	(	mpg123_string *	sb,
		size_t	news
	)

Change the size of a mpg123_string

Parameters

sb	string handle
news	new size in bytes

Returns

0 on error, 1 on success

Definition at line 59 of file stringbuf.c.

{
    if(!sb)
        return 0;
    debug3("resizing string pointer %p from %lu to %lu", (void*) sb->p, (unsigned long)sb->size, (unsigned long)new);
    if(new == 0)
    {
        if(sb->size && sb->p != NULL) free(sb->p);
        mpg123_init_string(sb);
        return 1;
    }
    if(sb->size != new)
    {
        char* t;
        debug("really!");
        t = (char*) safe_realloc(sb->p, new*sizeof(char));
        debug1("safe_realloc returned %p", (void*) t);
        if(t != NULL)
        {
            sb->p = t;
            sb->size = new;
            if(sb->size < sb->fill)
            {
                // Cut short the existing data, properly.
                sb->fill = sb->size;
                sb->p[sb->fill-1] = 0;
            }
            return 1;
        }
        else return 0;
    }
    else return 1; /* success */
}

Referenced by mpg123_copy_string(), and mpg123_grow_string().

mpg123_same_string()

MPG123_EXPORT int mpg123_same_string	(	mpg123_string *	a,
		mpg123_string *	b
	)

Determine if two strings contain the same data. This only returns 1 if both given handles are non-NULL and if they are filled with the same bytes.

Parameters

a	first string handle
b	second string handle

Returns

0 for different strings, 1 for identical

Definition at line 241 of file stringbuf.c.

{
    if(!a || !b)
        return 0;
    if(a->fill != b->fill)
        return 0;
    if(memcmp(a->p, b->p, a->fill))
        return 0;
    return 1;
}

Referenced by add_id3_picture(), and add_id3_text().

mpg123_set_string()

MPG123_EXPORT int mpg123_set_string	(	mpg123_string *	sb,
		const char *	stuff
	)

Set the content of a mpg123_string to a C-string

Parameters

sb	string handle
stuff	content to copy

Returns

0 on error, 1 on success

Definition at line 178 of file stringbuf.c.

{
    if(!sb)
        return 0;
    sb->fill = 0;
    return mpg123_add_string(sb, stuff);
}

Referenced by mpg123_new_string(), and mpg123_store_utf8().

mpg123_set_substring()

MPG123_EXPORT int mpg123_set_substring	(	mpg123_string *	sb,
		const char *	stuff,
		size_t	from,
		size_t	count
	)

Set the content of a mpg123_string to a C-substring

Parameters

sb	string handle
stuff	the future content
from	offset to copy from
count	number of characters to copy (a null-byte is always appended)

Returns

0 on error, 1 on success

Definition at line 170 of file stringbuf.c.

{
    if(!sb)
        return 0;
    sb->fill = 0;
    return mpg123_add_substring(sb, stuff, from, count);
}

mpg123_store_utf8()

MPG123_EXPORT int mpg123_store_utf8	(	mpg123_string *	sb,
		enum mpg123_text_encoding	enc,
		const unsigned char *	source,
		size_t	source_size
	)

Store text data in string, after converting to UTF-8 from indicated encoding A prominent error can be that you provided an unknown encoding value, or this build of libmpg123 lacks support for certain encodings (ID3 or ICY stuff missing). Also, you might want to take a bit of care with preparing the data; for example, strip leading zeroes (I have seen that).

Parameters

sb	target string
enc	mpg123 text encoding value
source	source buffer with plain unsigned bytes (you might need to cast from signed char)
source_size	number of bytes in the source buffer

Returns

0 on error, 1 on success (on error, mpg123_free_string is called on sb)

Definition at line 1604 of file libmpg123.c.

{
    switch(enc)
    {
#ifndef NO_ID3V2
        /* The encodings we get from ID3v2 tags. */
        case mpg123_text_utf8:
            id3_to_utf8(sb, mpg123_id3_utf8, source, source_size, 0);
        break;
        case mpg123_text_latin1:
            id3_to_utf8(sb, mpg123_id3_latin1, source, source_size, 0);
        break;
        case mpg123_text_utf16bom:
        case mpg123_text_utf16:
            id3_to_utf8(sb, mpg123_id3_utf16bom, source, source_size, 0);
        break;
        /* Special because one cannot skip zero bytes here. */
        case mpg123_text_utf16be:
            id3_to_utf8(sb, mpg123_id3_utf16be, source, source_size, 0);
        break;
#endif
#ifndef NO_ICY
        /* ICY encoding... */
        case mpg123_text_icy:
        case mpg123_text_cp1252:
        {
            mpg123_free_string(sb);
            /* Paranoia: Make sure that the string ends inside the buffer... */
            if(source[source_size-1] == 0)
            {
                /* Convert from ICY encoding... with force applied or not. */
                char *tmpstring = icy2utf8((const char*)source, enc == mpg123_text_cp1252 ? 1 : 0);
                if(tmpstring != NULL)
                {
                    mpg123_set_string(sb, tmpstring);
                    free(tmpstring);
                }
            }
        }
        break;
#endif
        default:
            mpg123_free_string(sb);
    }
    /* At least a trailing null of some form should be there... */
    return (sb->fill > 0) ? 1 : 0;
}

mpg123_strlen()

MPG123_EXPORT size_t mpg123_strlen	(	mpg123_string *	sb,
		int	utf8
	)

Count characters in a mpg123 string (non-null bytes or Unicode points). This function is of limited use, as it does just count code points encoded in an UTF-8 string, only loosely related to the count of visible characters. Get your full Unicode handling support elsewhere.

Parameters

sb	string handle
utf8	a flag to tell if the string is in utf8 encoding

Returns

character count

Definition at line 186 of file stringbuf.c.

{
    size_t i;
    size_t bytelen;
 
    /* Notions of empty string. If there's only a single character, it has to be the trailing zero, and if the first is the trailing zero anyway, we got empty. */
    if(!sb || sb->fill < 2 || sb->p[0] == 0) return 0;
 
    /* Find the first non-null character from the back.
       We already established that the first character is non-null
       That at fill-2 has to be null, though. */
    for(i=sb->fill-2; i>0; --i)
    if(sb->p[i] != 0) break;
 
    /* For simple byte strings, we are done now. */
    bytelen = i+1;
 
    if(!utf8) return bytelen;
    else
    {
        /* Work out the actual count of UTF8 bytes.
           This employs no particular encoding error checking. */
        size_t len = 0;
        for(i=0; i<bytelen; ++i)
        {
            /* Every byte that is not a continuation byte ( 0xc0 == 10xx xxxx ) stands for a character. */
            if((sb->p[i] & 0xc0) != 0x80) len++;
        }
        return len;
    }
}