Home · All Classes · All Functions ·

Versit API

Overview

Versit API provides a set of methods to parse/read (QVersitReader) and encode/write (QVersitWriter) versit* documents such as vCards (http://www.imc.org/pdi/). Currently QVersitReader and QVersitWriter support reading and writing vCard 2.1 and 3.0 formats.

Versit API also provides utilities to import (QVersitContactImporter) QContacts from versit documents and export (QVersitContactExporter) QContacts to versit documents.

[*] Versit is a trademark of the Internet Mail Consortium.

Usage

    // Create the input vCard
    QBuffer input;
    input.open(QBuffer::ReadWrite);
    QByteArray inputVCard =
        "BEGIN:VCARD\r\nVERSION:2.1\r\nFN:John Citizen\r\nN:Citizen;John;Q;;\r\nEND:VCARD\r\n";
    input.write(inputVCard);
    input.seek(0);

    // Parse the input into QVersitDocument(s)
    QVersitReader reader;
    reader.setDevice(&input);
    reader.readAll(); // Remember to check the return value

    // Import the QVersitDocument to a QContact
    QVersitDocument inputDocument = reader.result().takeFirst();
    QVersitContactImporter importer;
    QContact contact = importer.importContact(inputDocument);
    // Note that the QContact is not saved yet.
    // Use QContactManager::saveContact() for saving if necessary

    // Export the QContact back to a QVersitDocument
    QVersitContactExporter exporter;
    QVersitDocument outputDocument = exporter.exportContact(contact);

    // Encode the QVersitDocument back to a vCard
    QBuffer output;
    output.open(QBuffer::ReadWrite);
    QVersitWriter writer;
    writer.setDevice(&output);
    writer.setVersitDocument(outputDocument);
    writer.writeAll(); // Remember to check the return value

    // Read the vCard back to a QByteArray
    output.seek(0);
    QByteArray outputVCard(output.readAll());

Classes

Mapping the vCard constants

vCard properties are mapped to QContactDetails as follows:

    // Mappings from versit property names to Qt contact details
    const versitContactDetailMapping versitContactDetailMappings[] = {
        {"ADR",           QContactAddress::DefinitionName.str,
                          ""},
        {"BDAY",          QContactBirthday::DefinitionName.str,
                          QContactBirthday::FieldBirthday.str},
        {"FN",            QContactDisplayLabel::DefinitionName.str,
                          ""},
        {"GEO",           QContactGeolocation::DefinitionName.str,
                          ""},
        {"EMAIL",         QContactEmailAddress::DefinitionName.str,
                          QContactEmailAddress::FieldEmailAddress.str},
        {"IMPP",          QContactOnlineAccount::DefinitionName.str,
                          QContactOnlineAccount::SubTypeImpp.str},
        {"LOGO",          QContactOrganization::DefinitionName.str,
                          QContactOrganization::FieldLogo.str},
        {"N",             QContactName::DefinitionName.str,
                          ""},
        {"NICKNAME",      QContactNickname::DefinitionName.str,
                          QContactNickname::FieldNickname.str},
        {"NOTE",          QContactNote::DefinitionName.str,
                          QContactNote::FieldNote.str},
        {"ORG",           QContactOrganization::DefinitionName.str,
                          QContactOrganization::FieldName.str},
        {"PHOTO",         QContactAvatar::DefinitionName.str,
                          QContactAvatar::SubTypeImage.str},
        {"REV",           QContactTimestamp::DefinitionName.str,
                          ""},
        {"ROLE",          QContactOrganization::DefinitionName.str,
                          QContactOrganization::FieldRole.str},
        {"SOUND",         QContactAvatar::DefinitionName.str,
                          QContactAvatar::SubTypeAudioRingtone.str},
        {"TEL",           QContactPhoneNumber::DefinitionName.str,
                          QContactPhoneNumber::FieldNumber.str},
        {"TITLE",         QContactOrganization::DefinitionName.str,
                          QContactOrganization::FieldTitle.str},
        {"UID",           QContactGuid::DefinitionName.str,
                          QContactGuid::FieldGuid.str},
        {"URL",           QContactUrl::DefinitionName.str,
                          QContactUrl::FieldUrl.str},
        {"X-ANNIVERSARY", QContactAnniversary::DefinitionName.str,
                          ""},
        {"X-ASSISTANT",   QContactOrganization::DefinitionName.str,
                          QContactOrganization::FieldAssistantName.str},
        {"X-CHILDREN",    QContactFamily::DefinitionName.str,
                          QContactFamily::FieldChildren.str},
        {"X-GENDER",      QContactGender::DefinitionName.str,
                          QContactGender::FieldGender.str},
        {"X-IMPP",        QContactOnlineAccount::DefinitionName.str,
                          QContactOnlineAccount::SubTypeImpp.str},
        {"X-NICKNAME",    QContactNickname::DefinitionName.str,
                          QContactNickname::FieldNickname.str},
        {"X-SIP",         QContactOnlineAccount::DefinitionName.str,
                          ""},
        {"X-SPOUSE",      QContactFamily::DefinitionName.str,
                          QContactFamily::FieldSpouse.str}
    };

vCard type parameters are mapped to subtypes in QContactDetails as follows:

    // Mappings from versit TYPE parameters to Qt contact detail subtypes
    const versitMapping versitSubTypeMappings[] = {
        {"DOM",    QContactAddress::SubTypeDomestic.str},
        {"INTL",   QContactAddress::SubTypeInternational.str},
        {"POSTAL", QContactAddress::SubTypePostal.str},
        {"PARCEL", QContactAddress::SubTypeParcel.str},
        {"VOICE",  QContactPhoneNumber::SubTypeVoice.str},
        {"CELL",   QContactPhoneNumber::SubTypeMobile.str},
        {"MODEM",  QContactPhoneNumber::SubTypeModem.str},
        {"CAR",    QContactPhoneNumber::SubTypeCar.str},
        {"VIDEO",  QContactPhoneNumber::SubTypeVideo.str},
        {"FAX",    QContactPhoneNumber::SubTypeFacsimile.str},
        {"BBS",    QContactPhoneNumber::SubTypeBulletinBoardSystem.str},
        {"PAGER",  QContactPhoneNumber::SubTypePager.str},
        {"SWIS",   QContactOnlineAccount::SubTypeVideoShare.str},
        {"VOIP",   QContactOnlineAccount::SubTypeSipVoip.str}
    };

File extensions in vCards are mapped to the file system file extensions as follows:

    // Mappings from file types in versit specifications to file extensions
    const versitMapping versitFileExtensionMappings[] = {
        {"JPEG", "JPG"},
        {"WAVE", "WAV"},
        {"PICT", "PCT"},
        {"TIFF", "TIF"},
        {"MPEG", "MPG"},
        {"MPEG2", "M2P"},
        {"QTIME", "QT"},
        {"AIFF", "AIF"},
        {"GIF", "GIF"}
    };


Copyright © 2009 Nokia Corporation and/or its subsidiary(-ies) Trademarks
Qt Mobility Project 1.0.0 (Technology Preview)