Qt Mobility中Contacts框架介绍

转载时请注明出处和作者联系方式
文章出处：http://blog.youkuaiyun.com/jack0106
作者联系方式：冯牮 fengjian0106@yahoo.com.cn

一．基础

说明

这一部分是对核心类的介绍，初次看本文档的时候，建议从第二部分开始看，先对QContact的用法有个大概的印象，然后再倒回来，看这里的基础介绍。

当然，真正开发的时候，api手册是最好的参考文档。

Main classes(7个)

QContact------Represents an addressbook contact

 

QContactAbstractRequest------Mechanism for asynchronous requests to be made of a manager if it supports them

 

QContactAction------Interface for performing an action on a QContact or QContactDetail

 

QContactDetail------Represents a single, complete detail about a contact

 

QContactFilter------Used to select contacts made available through a QContactManager

 

QContactManager------Interface which allows clients with access to contact information stored in a particular backend

 

QContactRelationship------Describes a one-to-one relationship between a locally-stored contact and another (possibly remote) contact

 

重点需要搞明白的是其中的三个类：QContact，QContactDetail，QContactManager

QContact

    Class QContact表示地址本里面的联系人。

一个QContact对象，可以表示一个个体的人、一个组(集合)或者是其他类型的contacts。除此之外，一个QContact对象还包含了其他的一些信息，比如这个contact所属的relationships，以及和这个contact交互的方法(QContactAction)。

一个QContact对象包含有一系列的details(比如name，phone numbers，email addresses)。每一个detail(可能包含有多个fields)都是QContactDetail的继承类，QContact可以通过多种方式来获取这些details。

根据一个QContact的不同的details，可以在这个contact上执行某种actions。一个QContact对象，可以通过函数接口来获取它支持的所有的actions，也可以获取支持某个action的所有details(比如，支持"Call" action 的所有phone number)。

一个QContact可以含有一个或者多个与其他contacts的relationships。比如，一个group contact和一个contact就可以拥有"HasMember"这样的relationship，这个contact就是该group contact的成员。

QContact对象本质上是一个位于内存中的地址本联系人，而且不属于任何一个特定的QContactManager。当从QContactManager中取出一个QContact后，位于内存中的这个contact和QContactManager中对应的原始的contact，就是完全独立的两个contact，如果修改了内存中的这个contact，除非将它重新存储回QContactManager，否则的话，这些修改是不会影响到QContactManager中对应的那个contact的。每个QContact都有一个和它关联的ID，这样的话，就可以通过QContactManager发出的信号来跟踪某个具体的QContact。

QContact包含几个强制性的details：

<1> QContactType，这个描述的是contact的类型(个体contact，或者group等等)

<2> QContactDisplayLabel，用来显示的一个文本信息。

 

如果编辑过一个QContact(保存或者删除了details)，需要重新通过某个QContactManager来获取该contact的QContactDisplayLabel，因为不同的managers有不同的设置。

 

看一下QContact的api接口函数。

1. QContactId  id () const

        类QContactId表示的一个contact在某个特定的manager里面的唯一标识符。

        它是由manager的URI和这个contact在该manager里面的local id(QContactLocalId )组成的。

        一个null的QContactId，是由一个空的manager URI和一个无效的QContactLocalId(0)组成的。

        QContactId不是QContactDetail。

 

2. QContactLocalId  localId () const

QContactLocalId  是一个类型，不是类------typedef QContactLocalId

QContactLocalId 表示的是一个contact在它的manager里面的独一无二的id。

大部分的函数接口，都是使用QContactLocalId作为参数。有一些函数(包括links to contacts outside a particular manager)使用manager URI作为参数。这个URI就存在QContactId里面。

无效的QContactLocalId其实就是0。

 

补充：

还有一个QContactDetail 的子类—QcontactGuid，这个也是表示id，但是它表示的是一个contact的全局的唯一id，它的用处是用来和其他的数据库做同步。

 

3. Detail相关的函数(最经常使用的，就是这些detail相关的函数，比如获取detail，存储detail等等)

void  clearDetails () 

QContactDetail  detail ( const QString & definitionName ) const 

QContactDetail  detail ( const QLatin1Constant & definitionName ) const 

T  detail () const 

QContactDetail  detailWithAction ( QContactAction * action ) const 

QList<QContactDetail>  details ( const QString & definitionName = QString() ) const 

QList<QContactDetail>  details ( const QString & definitionName, const QString & fieldName, const QString & value ) const 

QList<QContactDetail>  details ( const QLatin1Constant & definitionName ) const 

QList<QContactDetail>  details ( const QLatin1Constant & definitionName, const QLatin1Constant & fieldName, const QString & value ) 

QList<T>  details () const 

QList<T>  details ( const QString & fieldName, const QString & value ) const 

QList<QContactDetail>  detailsWithAction ( QContactAction * action ) const 

QContactDetail  preferredDetail ( const QString & actionName ) const 

QMap<QString, QContactDetail>  preferredDetails () const

bool  removeDetail ( QContactDetail * detail ) 

bool  saveDetail ( QContactDetail * detail ) 

bool  setPreferredDetail ( const QString & actionName, const QContactDetail & preferredDetail )

 

///

QString  displayLabel () const

void  setType ( const QString & type ) 

void  setType ( const QContactType & type ) 

QString  type () const

这4个函数其实都是更方便的函数，QContactDisplayLabel和QContactType都是两个子类QContactDetail。

 

4. 其他的api

QList<QContactActionDescriptor>  availableActions ( const QString & vendorName = QString(), int implementationVersion = -1 ) const

 

QList<QContactId>  relatedContacts ( const QString & relationshipType = QString(), QContactRelationship::Role role = QContactRelationship::Either ) const 

 

QList<QContactRelationship>  relationships ( const QString & relationshipType = QString() ) const

5. 

 

 

 

QContactDetail(重点)

QContactDetail结构示意图

Access Constraints (访问限制)
Definition Name (关联的QContactDetailDefinition的名字)
Key(field的名字，Latin字符串，QLatin1Constant)	Value(field的值，QStrings or QVariant)
QContactDetail::FieldContext
QContactDetail::FieldContext
QContactDetail::FieldLinkedDetailUris
……	……