diff options
Diffstat (limited to 'doc/src')
| -rw-r--r-- | doc/src/contactsschema.qdoc | 66 |
1 files changed, 36 insertions, 30 deletions
diff --git a/doc/src/contactsschema.qdoc b/doc/src/contactsschema.qdoc index c0f8907613..eab9d70759 100644 --- a/doc/src/contactsschema.qdoc +++ b/doc/src/contactsschema.qdoc @@ -77,16 +77,10 @@ The leaf details that form the default schema are as follows: \annotatedlist contacts-details -In the default schema, each of these definitions have various access and uniqueness constraints. -Additionally, fields of the definitions may have an access constraint of read-only defined for them. - \section2 Detail Definition Uniqueness A uniqueness constraint on a detail definition means that for any \l{QContact}, only one detail of that -definition may be saved. Generally, it is information for which a contradicting detail would mean -inability to identify the contact. Please note that some details, such as \l{QContactBirthday} or -\l{QContactName}, do not have a uniqueness constraint, since in different contexts, different information -may be valid. +definition may be saved. The leaf classes which have a uniqueness constraint in the default schema are as follows: \list @@ -96,43 +90,55 @@ The leaf classes which have a uniqueness constraint in the default schema are as \o \l{QContactGuid} \endlist -\section2 Detail Definition Access Constraints +\section2 Detail Access Constraints + +Some details in a contact retrieved from a manager may have access constraints set. +An access constraint on a detail means that the detail may not be removed (if the access constraint is \c QContactDetail::Irremovable) +or updated (if the access constraint is \c QContactDetail::ReadOnly) by the client. If the client attempts to save an updated +version of a read-only detail in a contact, or remove a detail which is irremovable from a contact, the operation will succeed; +however those updates to the contact will be ignored by the manager when the contact is saved there. -An access constraint on a detail definition means that for any detail of that definition in a \l{QContact}, -the specified access constraints apply. For example, the \l{QContactDisplayLabel} is defined in the default -schema as a read-only detail definition; meaning that details of that type in a contact cannot be created, modified or deleted by -the client, but are provided by the backend (in the case of \l{QContactDisplayLabel}, automatically synthesized -by the backend from various details of the contact). +For example, the \l{QContactDisplayLabel} is defined in the default schema as a read-only, irremovable detail, +meaning that it may not be modified or deleted by the client, but are provided by the backend (in the case +of \l{QContactDisplayLabel}, automatically synthesized by the backend from various details of the contact, like +the \l{QContactName}, \l{QContactNickname}, etc). -There are three possible detail definition-level access constraints: read-only, create-only and no-constraint. -A read-only constraint ensures that clients cannot create, delete or modify details of that definition; a create-only -constraint ensures that clients cannot modify details of that definition, but can create them (with whichever -values they see fit); if no constraint is specified, details of that definition may be created, modified or deleted as required. +There are three possible detail access constraints: read-only, irremovable and no constraint. +A read-only constraint ensures that clients cannot modify the values stored in such details in the persistent +copy of the contact (that is, the contact as it is stored in the manager); the irremovable constaint ensures +that a particular detail may not be removed by clients. In general, most details which are read only will +also be irremovable, and vice versa. One exception to this is the \l{QContactType} detail, which is +irremovable but may be updated by clients as desired. +Details with no constraint may be added, updated and removed as desired by the client. Changes to such details +in a contact will be persisted in the manager when the client calls \l{QContactManager::saveContact()}. -Please see the documentation of \l{QContactDetailDefinition} for more information on access constraints. +Please see the documentation of \l{QContactDetail} for more information on access constraints. The leaf classes which have access constraints in the default schema are as follows: \list - \o \l{QContactGuid} is \c QContactDetailDefinition::CreateOnly - \o \l{QContactSyncTarget} is \c QContactDetailDefinition::CreateOnly - \o \l{QContactTimestamp} is \c QContactDetailDefinition::ReadOnly - \o \l{QContactDisplayLabel} is \c QContactDetailDefinition::ReadOnly + \o \l{QContactGuid} is \c QContactDetail::ReadOnly and \c QContactDetail::Irremovable + \o \l{QContactSyncTarget} is \c QContactDetail::ReadOnly and \c QContactDetail::Irremovable + \o \l{QContactTimestamp} is \c QContactDetail::ReadOnly and \c QContactDetail::Irremovable + \o \l{QContactPresence} is \c QContactDetail::ReadOnly and \c QContactDetail::Irremovable + \o \l{QContactDisplayLabel} is \c QContactDetail::ReadOnly and \c QContactDetail::Irremovable + \o \l{QContactType} is \c QContactDetail::Irremovable \endlist Furthermore, in the default schema, every contact is required to have at least two details by default: a \l{QContactType} which describes the type of entity that the contact represents (for example, a person or a group), and a \l{QContactDisplayLabel} which holds the default display label for the contact. -\section2 Field Access Constraints +\section2 Backend-provided Details -Furthermore, some fields of some definitions are also constrained to be read-only. This is information which is generated or automatically -provided by the backend, which is related to user-provided information that is also stored in the detail. +As described in the section on detail access constraints, some details are provided by the backend, +such as \l{QContactDisplayLabel} and \l{QContactPresence}. When the client attempts to save a \l{QContact} +that contains these details, these details will be ignored by the backend (since any values in this field +are synthesized by the backend). This means that while clients may (for example) add a +\l{QContactPresence} detail to a \l{QContact}, it will not be persisted in the manager when the +client attempts to save that contact. -The eponymous example of this is the \l{QContactOnlineAccount} leaf detail, which has unconstrained fields which store the URI and service -provider of the account, and several read-only fields in which are stored presence information, status messages, and service availability. +Precisely which details are backend-provided is backend specific; some backends provide more details +than others. -Currently, the \l{QContactOnlineAccount} is the only leaf detail with field-level access constraints. Every field in details of this -type are \c QContactDetailDefinition::ReadOnly except for \c QContactOnlineAccount::FieldAccountUri and -\c QContactOnlineAccount::FieldServiceProvider, which have no constraint. */ |