martin: doc/kolab-formats/kolab2 Contacts,1.1,1.2

[cvs at intevation.de]

Author: martin

Update of /kolabrepository/doc/kolab-formats/kolab2
In directory doto:/tmp/cvs-serv1600

Modified Files:
	Contacts 
Log Message:
Martin K.: Cosmetics, what to do with unknown properties, Example needs update (some inconsistencies), properties are probably complete


Index: Contacts
===================================================================
RCS file: /kolabrepository/doc/kolab-formats/kolab2/Contacts,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -d -r1.1 -r1.2
--- Contacts	29 May 2004 10:29:11 -0000	1.1
+++ Contacts	29 May 2004 22:49:41 -0000	1.2
@@ -1,163 +1,166 @@
-This is an early _draft_ of the specification for handling contacts in a 
-common format for the KDE Kolab client, the Kolab web client and the Toltec  
+This is an early _draft_ of the specification for handling contacts in a
+common format for the KDE Kolab client, the Kolab web client and the Toltec
 Kolab Connector for Outlook.
 
-The format is basically derived from an reverse engineering effort of the 
+The format is basically derived from an reverse engineering effort of the
 Outlook data structures using Outlook Spy.
 
 In general we want a common format for
 
-	- calendars
-	- Todos
-	- Journal (secondary goal)
-	- Notes
-	- contacts
+        - Calendars
+        - Todos
+        - Journal (secondary goal)
+        - Notes
+        - Contacts
 
-It has been discussed that defining a common format for contacts are the most 
-difficult part as the available standards are umbigious and the vcard 
-standard does unfortunately not guarantee interoperability between different 
-implementations. 
+It has been discussed that defining a common format for contacts are the most
+difficult part as the available standards are umbigious and the vcard
+standard does unfortunately not guarantee interoperability between different
+implementations.
 
-I therefore chose the Outlook way of handling contact data because on one hand 
-it is a defacto standard, reasonable enough and on the other hand we value 
-interoperability with Outlook very much while changing the way how Outlook 
+I therefore chose the Outlook way of handling contact data because on one hand
+it is a defacto standard, reasonable enough and on the other hand we value
+interoperability with Outlook very much while changing the way how Outlook
 handles contact data is beyond our current capabilities.
 
-In addition I propose that the opensource clients (Kontact and Webclient) 
-adopt this standard and code appropriate forms to handle the data. From a 
-user interface point of view imho these clients can do better than Outlook 
+In addition I propose that the opensource clients (Kontact and Webclient)
+adopt this standard and code appropriate forms to handle the data. From a
+user interface point of view imho these clients can do better than Outlook
 though.
 
-In addition I plan to adapt our kInetOrgPerson objectclass to become more 
-compatible to the Outlook contacts. 
+In addition I plan to adapt our kInetOrgPerson objectclass to become more
+compatible to the Outlook contacts.
 
-This should allow to copy LDAP addressbook entries to a contacts folder which 
-is then compatible to all Kolab clients. Beeing able to share contacts 
+This should allow to copy LDAP addressbook entries to a contacts folder which
+is then compatible to all Kolab clients. Beeing able to share contacts
 between clients is a very important feature for our users.
 
 We use Unix linefeed convention (\n) and UTF-8 for the encoding of strings.
 Binary data if required is encoded using the vcard compatible "B" encoding.
 
->
-> CONTACT_FIELD (FULL_NAME, "full_name")
-> CONTACT_FIELD (FAMILY_NAME, "family_name"),
-> CONTACT_FIELD (GIVEN_NAME, "given_name"),
-> CONTACT_FIELD (ADDITIONAL_NAME, "middle_name"),
-> CONTACT_FIELD (NAME_SUFFIX, "name_suffix"),
-> CONTACT_FIELD (TITLE, "title"),
-> CONTACT_FIELD (ORG, "org"),
-> CONTACT_FIELD (FILE_AS, "file_as"),
-> CONTACT_FIELD (PHONE_CALLBACK, "callback_phone"),
-> CONTACT_FIELD (PHONE_BUSINESS_FAX, "business_fax"),
-> CONTACT_FIELD (PHONE_HOME_FAX, "home_fax"),
-> CONTACT_FIELD (PHONE_HOME, "home_phone"),
-> CONTACT_FIELD (PHONE_HOME_2, "home_phone_2"),
-> CONTACT_FIELD (PHONE_ISDN, "isdn"),
-> CONTACT_FIELD (PHONE_MOBILE, "mobile_phone"),
-> CONTACT_FIELD (PHONE_COMPANY, "company_phone"),
-> CONTACT_FIELD (PHONE_OTHER_FAX, "other_fax"),
-> CONTACT_FIELD (PHONE_PAGER, "pager"),
-> CONTACT_FIELD (PHONE_BUSINESS, "business_phone"),
-> CONTACT_FIELD (PHONE_BUSINESS_2, "business_phone_2"),
-> CONTACT_FIELD (PHONE_TELEX, "telex"),
-> CONTACT_FIELD (PHONE_TTYTDD, "tty"),
-> CONTACT_FIELD (PHONE_ASSISTANT, "assistant_phone"),
-> CONTACT_FIELD (PHONE_CAR, "car_phone"),
-> CONTACT_FIELD (PHONE_OTHER, "other_phone"),
-> CONTACT_FIELD (URL, "url"),
-> CONTACT_FIELD (ORG_UNIT, "org_unit"),
-> MAPI_ID_FIELD (PHONE_RADIO, PR_RADIO_TELEPHONE_NUMBER, "radio"),
-> CONTACT_FIELD (OFFICE, "office"),
-> MAPI_ID_FIELD (PHONE_PRIMARY, PR_PRIMARY_TELEPHONE_NUMBER,
-> "primary_phone"), CONTACT_FIELD (ROLE, "role"),
-> CONTACT_FIELD (MANAGER, "manager"),
->
-> CONTACT_FIELD (ASSISTANT, "assistant"),
-> CONTACT_FIELD (NICKNAME, "nickname"),
-> CONTACT_FIELD (SPOUSE, "spouse"),
->
-> We allow exactly these three Email Addresses. Email type is always SMTP. We
-> explicitly disallow Exchange type or X-400 addresses.
->
-> EMAIL_FIELD (EMAIL, "email"),
->         EMAIL_ENTRID,  (only Outlook)
->         EMAIL_ADDRESS,
->         EMAIL_DISPLAY_NAME
->         CONTACTS_EMAIL2
->
-> EMAIL_FIELD (EMAIL_2, "email_2"),
->         EMAIL_ENTRID,  (only Outlook)
->         EMAIL_ADDRESS,
->         EMAIL_DISPLAY_NAME
->         CONTACTS_EMAIL2
->
-> EMAIL_FIELD (EMAIL_3, "email_3"),
->         EMAIL_ENTRID, (only Outlook))
->         EMAIL_ADDRESS,
->         EMAIL_DISPLAY_NAME
->         CONTACTS_EMAIL3
->
-> ADDRESS_FIELD (ADDRESS_BUSINESS, "business_address"),
->         CONTACTS_HOME_PO_BOX,
->         CONTACTS_HOME_STREET,
->         CONTACTS_HOME_CITY,
->         CONTACTS_HOME_STATE,
->         CONTACTS_HOME_ZIP,
->         CONTACTS_HOME_COUNTRY,
->
-> ADDRESS_FIELD (ADDRESS_HOME, "home_address"),
->         CONTACTS_HOME_PO_BOX,
->         CONTACTS_HOME_STREET,
->         CONTACTS_HOME_CITY,
->         CONTACTS_HOME_STATE,
->         CONTACTS_HOME_ZIP,
->         CONTACTS_HOME_COUNTRY,
->
-> ADDRESS_FIELD (ADDRESS_OTHER, "other_address"),
->         CONTACTS_HOME_PO_BOX,
->         CONTACTS_HOME_STREET,
->         CONTACTS_HOME_CITY,
->         CONTACTS_HOME_STATE,
->         CONTACTS_HOME_ZIP,
->         CONTACTS_HOME_COUNTRY,
->
->
-> DATE_FIELD (BIRTH_DATE, "birth_date"),
-> DATE_FIELD (ANNIVERSARY, "anniversary"),
-> CAL_FIELD (FBURL, "fburl"),
->
-> HTTPMAIL_FIELD (NOTE, TEXT_DESCRIPTION, "note"),
-> EXCHANGE_FIELD (CATEGORIES, KEYWORDS, "categories")
->
-> The name of a contact in the address book is derived according to the
-> following first match rule:
->
-> FULL_NAME, FILE_AS, EMAIL, EMAIL1, EMAIL2, ORG, TITLE, NULL
->
-> Synonyms:
-> full_name displayName
-> given_name givenName
-> family_name sn
-> email mail
-> business_phone telephoneNumber
-> business_phone_2 otherTelephone
-> home_phone homePhone
-> home_phone2_ otherHomePhone
-> mobile_phone mobile
-> business_fax facsimileTelephoneNumber
-> other_fax otherFacsimileTelephoneNumber
-> pager Pager
-> org company
-> org_unit department
-> office physicalDeliveryOfficeName
-> title Title
-> manager Manager
-> location l
-> country c
-> zip postalCode
-> url wwwHomePage
-> note info
-> fburl msExchFBURL
+In case a Kolab client does not understand a property it is mandatory to
+preserve it unchanged. Therefore Kolab clients must be able to store unknown
+properties in their local data structures. The foreign property is then restored
+when the contact is updated in the repository.
+
+CONTACT_FIELD (FULL_NAME, "full_name")
+CONTACT_FIELD (FAMILY_NAME, "family_name"),
+CONTACT_FIELD (GIVEN_NAME, "given_name"),
+CONTACT_FIELD (ADDITIONAL_NAME, "middle_name"),
+CONTACT_FIELD (NAME_SUFFIX, "name_suffix"),
+CONTACT_FIELD (TITLE, "title"),
+CONTACT_FIELD (ORG, "org"),
+CONTACT_FIELD (FILE_AS, "file_as"),
+CONTACT_FIELD (PHONE_CALLBACK, "callback_phone"),
+CONTACT_FIELD (PHONE_BUSINESS_FAX, "business_fax"),
+CONTACT_FIELD (PHONE_HOME_FAX, "home_fax"),
+CONTACT_FIELD (PHONE_HOME, "home_phone"),
+CONTACT_FIELD (PHONE_HOME_2, "home_phone_2"),
+CONTACT_FIELD (PHONE_ISDN, "isdn"),
+CONTACT_FIELD (PHONE_MOBILE, "mobile_phone"),
+CONTACT_FIELD (PHONE_COMPANY, "company_phone"),
+CONTACT_FIELD (PHONE_OTHER_FAX, "other_fax"),
+CONTACT_FIELD (PHONE_PAGER, "pager"),
+CONTACT_FIELD (PHONE_BUSINESS, "business_phone"),
+CONTACT_FIELD (PHONE_BUSINESS_2, "business_phone_2"),
+CONTACT_FIELD (PHONE_TELEX, "telex"),
+CONTACT_FIELD (PHONE_TTYTDD, "tty"),
+CONTACT_FIELD (PHONE_ASSISTANT, "assistant_phone"),
+CONTACT_FIELD (PHONE_CAR, "car_phone"),
+CONTACT_FIELD (PHONE_OTHER, "other_phone"),
+CONTACT_FIELD (URL, "url"),
+CONTACT_FIELD (ORG_UNIT, "org_unit"),
+MAPI_ID_FIELD (PHONE_RADIO, PR_RADIO_TELEPHONE_NUMBER, "radio"),
+CONTACT_FIELD (OFFICE, "office"),
+MAPI_ID_FIELD (PHONE_PRIMARY, PR_PRIMARY_TELEPHONE_NUMBER,"primary_phone"),
+CONTACT_FIELD (ROLE, "role"),
+CONTACT_FIELD (MANAGER, "manager"),
+
+CONTACT_FIELD (ASSISTANT, "assistant"),
+CONTACT_FIELD (NICKNAME, "nickname"),
+CONTACT_FIELD (SPOUSE, "spouse"),
+
+We allow exactly these three Email Addresses. Email type is always SMTP. We
+explicitly disallow Exchange type or X-400 addresses.
+
+EMAIL_FIELD (EMAIL, "email"),
+         EMAIL_ENTRID,  (only Outlook)
+         EMAIL_ADDRESS,
+         EMAIL_DISPLAY_NAME
+         CONTACTS_EMAIL2
+
+EMAIL_FIELD (EMAIL_2, "email_2"),
+         EMAIL_ENTRID,  (only Outlook)
+         EMAIL_ADDRESS,
+         EMAIL_DISPLAY_NAME
+         CONTACTS_EMAIL2
+
+EMAIL_FIELD (EMAIL_3, "email_3"),
+         EMAIL_ENTRID, (only Outlook))
+         EMAIL_ADDRESS,
+         EMAIL_DISPLAY_NAME
+         CONTACTS_EMAIL3
+
+ADDRESS_FIELD (ADDRESS_BUSINESS, "business_address"),
+         CONTACTS_HOME_PO_BOX,
+         CONTACTS_HOME_STREET,
+         CONTACTS_HOME_CITY,
+         CONTACTS_HOME_STATE,
+         CONTACTS_HOME_ZIP,
+         CONTACTS_HOME_COUNTRY,
+
+ADDRESS_FIELD (ADDRESS_HOME, "home_address"),
+         CONTACTS_HOME_PO_BOX,
+         CONTACTS_HOME_STREET,
+         CONTACTS_HOME_CITY,
+         CONTACTS_HOME_STATE,
+         CONTACTS_HOME_ZIP,
+         CONTACTS_HOME_COUNTRY,
+
+ADDRESS_FIELD (ADDRESS_OTHER, "other_address"),
+         CONTACTS_HOME_PO_BOX,
+         CONTACTS_HOME_STREET,
+         CONTACTS_HOME_CITY,
+         CONTACTS_HOME_STATE,
+         CONTACTS_HOME_ZIP,
+         CONTACTS_HOME_COUNTRY,
+
+DATE_FIELD (BIRTH_DATE, "birth_date"),
+DATE_FIELD (ANNIVERSARY, "anniversary"),
+CAL_FIELD (FBURL, "fburl"),
+
+HTTPMAIL_FIELD (NOTE, TEXT_DESCRIPTION, "note"),
+EXCHANGE_FIELD (CATEGORIES, KEYWORDS, "categories")
+
+The name of a contact in the address book is derived according to the
+following first match rule:
+
+FULL_NAME, FILE_AS, EMAIL, EMAIL1, EMAIL2, ORG, TITLE, NULL
+
+Synonyms:
+full_name displayName
+given_name givenName
+family_name sn
+email mail
+business_phone telephoneNumber
+business_phone_2 otherTelephone
+home_phone homePhone
+home_phone2_ otherHomePhone
+mobile_phone mobile
+business_fax facsimileTelephoneNumber
+other_fax otherFacsimileTelephoneNumber
+pager Pager
+org company
+org_unit department
+office physicalDeliveryOfficeName
+title Title
+manager Manager
+location l
+country c
+zip postalCode
+url wwwHomePage
+note info
+fburl msExchFBURL
 
 Example:
 Content-Type: text/directory; profile="vcard"; charset=iso-8859-15