String Encoding

This topic describes the string encoding used by the AVBlocks Plus API.

Unicode Strings

The AVBlocks API uses UTF-16 unicode encoding.

The AVBlocks API character type is char_t, where char_t represents a UTF-16 character and is defined as a 16 bit unsigned integer on all platforms (Windows, Mac and Linux).

Note: A Unicode character can be expressed by 1 or 2 UTF-16 code units, i.e. by 2 or 4 bytes.

AVBlocks Plus converts strings for you: the classes that use std::string (TMediaSocket, TTranscoder, TMediaInfo, TMetaAttribute) take and return UTF-8 strings, and the wide-character variants (TMediaSocketW, TTranscoderW, TMediaInfoW) use std::wstring.

Windows

On Windows the char_t type is the same as the wchar_t type. Your Windows application must be compiled for Unicode OR alternatively you should convert strings to wchar_t before passing calling the AVBlocks API.

Mac

CoreFoundation

A CFStringRef can be bridged to NSString, which provides a UTF-8 string that AVBlocks Plus accepts:

// Get a UTF-8 string from CFStringRef and pass it to AVBlocks Plus

CFStringRef theCFString;
const char* theStringUtf8 = [(__bridge NSString*)theCFString UTF8String];

TMetaAttribute metaAttribute;
metaAttribute.name(primo::codecs::Meta::Album)
             .value(theStringUtf8);

Foundation

NSString provides a UTF-8 string through UTF8String, which AVBlocks Plus accepts:

// Get a UTF-8 string from NSString and pass it to AVBlocks Plus

NSString* theString;
const char* theStringUtf8 = [theString UTF8String];

TMetaAttribute metaAttribute;
metaAttribute.name(primo::codecs::Meta::Album)
             .value(theStringUtf8);

Command Line

On Mac / Unix, wchar_t is defined as a 32-bit unsigned integer by default. AVBlocks Plus converts between your UTF-8 strings and char_t (UTF-16 encoding) for you. For example, TMetaAttribute::value returns a UTF-8 std::string. The info_metadata_file sample demonstrates this:

auto attlist = meta.attributes();
cout << attlist.count() << " attributes:" << endl;

for (int i = 0; i < attlist.count(); ++i)
{
    auto attr = attlist.at(i);
    cout << setw(15) << left << attr.name() << ": " << attr.value() << endl;
}

Linux

Command Line

On Linux, wchar_t is defined as a 32-bit unsigned integer by default. AVBlocks Plus converts between your UTF-8 strings and char_t (UTF-16 encoding) for you. For example, TMetaAttribute::value returns a UTF-8 std::string. The info_metadata_file sample demonstrates this:

auto attlist = meta.attributes();
cout << attlist.count() << " attributes:" << endl;

for (int i = 0; i < attlist.count(); ++i)
{
    auto attr = attlist.at(i);
    cout << setw(15) << left << attr.name() << ": " << attr.value() << endl;
}

ANSI Strings

The text constants which are part of the AVBlocks API itself are plain 8-bit ANSI char for convenience. For example, the primo::codecs::Meta namespace contains metadata attribute names defined as ANSI strings:

/**
    Metadata attribute names
*/
namespace Meta
{
    /** Album */
    static const char Album[]				= "Album";

    /** Composer */
    static const char Composer[]			= "Composer";

    /** Genre */
    static const char Genre[]				= "Genre";

    /** Copyright */
    static const char Copyright[]			= "Copyright";
}