Home · All Classes · All Functions ·

Versit API (technology preview)

Warning: This API should be considered in a technology preview state. It is under development and subject to change.

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 QVersitDocuments
        QVersitReader reader;
        reader.setDevice(&input);
        reader.startReading(); // Remember to check the return value
        reader.waitForFinished();

        // Convert the QVersitDocuments to QContacts
        QList<QVersitDocument> inputDocuments = reader.results();
        QVersitContactImporter importer;
        QList<QContact> contacts = importer.importContacts(inputDocuments);
        // Note that the QContacts are not saved yet.
        // Use QContactManager::saveContacts() for saving if necessary

        // Export the QContacts back to QVersitDocuments
        QVersitContactExporter exporter;
        QList<QVersitDocument> outputDocuments = exporter.exportContacts(contacts);

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

        // 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}
    };


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