vCard Class Library for .

NET
Copyright (c) 2007-2009 David Pinch (davepinch@gmail.com).

Please refer to README.TXT in the distribution archive. If you do

not have a copy of the archive, you may download the latest version
of this library from http://www.thoughtproject.com/Libraries/vCard/
This library is distributed under the terms of the Lesser General
Public License. Please refer to LICENSE.TXT for the exact terms.

History

------------------------------------------------------------------------
2009-10-08: Version 0.4
------------------------------------------------------------------------

1. Unit tests have been upgraded to NUnit 2.5.2.

2. Per the Microsoft guidelines for class library development, all string
properties are expected to return String.Empty instead of null (in
cases where the property is blank). This is already the case in
this library but the implementation was problematic. Instead each
string getter now takes the following form:

return this.property ?? string.Empty;

Previously the code attempted to translate null to string.Empty whenever

the value was assigned -- in the constructor, in the setter, etc. This
is prone to error. The form shown above is used instead.

3. Renames. The following types were renamed to comply with standard

naming conventions. Any code will need to be fixed. Fixes should be
minor only.

Per class library design guidelines, flag enumerations should be

named with a plural name. See FxCop rule FlagsEnumsShouldHavePluralNames.
These changes are simple to fix in code; simple add an "s" whereever you
reference the enumeration.

- vCardDeliveryAddressType => vCardDeliveryAddressTypes

- vCardPhoneType => vCardPhoneTypes
- vCardWebSiteType => vCardWebSiteTypes

Per class library design guidelines, the term "WebSite" is actually

a discrete term "website". Refer to rule CompoundWordsShouldBeCasedCorrectly
in FxCop. The following types have been renamed:

- vCardWebSite => vCardWebsite

- vCardWebSiteCollection => vCardWebsiteCollection
- vCardWebSiteType => vCardWebsiteType

3. Non-Breaking Changes:

The following changes are internal fixes that are not expected to
cause compilation issues.

- Assembly marked as language neutral (set to U.S. English).

 - vCardStandardWriter no longer unnecessarily initializes embedInternetImages
- vCardStandardWriterOptions is now a flags enumeration
- vCardSubpropertyCollection uses StringComparison.OrdinalIgnoreCase.
- vCardStandardReader recognizes the date format exported by Outlook 2007.
- Updated various XML comments.

Some collections have overloads that return the index of a named

value, e.g. vCardSubpropertyCollection.IndexOf(name). Internally
these functions perform a comparison using StringComparison.OrdinalIgnoreCase.
This should have no impact unless you were using the library under
a very unique language/environment.

------------------------------------------------------------------------
2007-08-xx: Version 0.3
------------------------------------------------------------------------

Thank you to many people who have written with kind comments and
suggestions for the library. The biggest change in this version
is a complete refactoring of the code for reading and writing
the file formats. The main vCard object model is now a generic
model. Format-specific code has been moved to separate classes
for easier maintenance and support for vCard-compatible formats.

Some changes will probably break your code. For example, the
library now supports multiple notes (previously only one note
per vCard was supported). The majority of changes will be
easy to fix, usually just by using the Intellisense(tm) in your
Visual Studio IDE. Please refer to the Unit Testing solution
if you need examples of using the API in various ways. The
number of unit tests have been expanded substantially.

- Added support for quoted-printable and standard MIME escape

encoding. The read/write process has been completely refactored
into a separate API to better support multiple vCard formats.

- Added vCardReader and vCardWriter, both abstract classes. They

define the core interfaces for creating format-specific readers
and writers.

- Added vCardStandardReader and vCardStandardWriter. These two

classes implement the vCard 2.1 and 3.0 text format specifications.
These classes are fairly complex due to the wide variety of
interpretations found in the wild!

- Removed all format and encoding-specific code from the main

vCard object model. Anything format-specific is expected to
be implemented in a reader or writer class. Currently only
the 2.1 and 3.0 formats are implemented, although future
versions will support RFD, hCard and other variations.
Therefore it makes no sense to have anything format-specific
in the main object model.

- Added support for multiple web sites. The vCard.Url property

was removed in favor of vCard.WebSites, a collection. See
new items: vCardWebSite, vCardWebSiteCollection, and
vCardWebSiteType. Import and export logic also updated.
 - Added support for multiple notes/comments. The vCard.Note
property was removed in favor of vCard.Notes, a collection.

- Added support for delivery addresses and delivery labels.

The current level of support is sufficient for Microsoft Outlook
but needs some more work for total vCard compliance.

- Added vCard.AccessClassification. This indicates the

intended access/permissions of the vCard, such as private,
public or confidential. It corresponds to the CLASS
property of the vCard specification.

- Added vCard.Categories (a string collection). This contains

any user-defined categories or keywords. It corresponds
with the CATEGORIES property of the vCard specification.

- Added vCard.DisplayName. This maps to the NAME property and

specifies the display name of the vCard. A vCard application
might show this name as a title or header.

- Added vCard.Latitude and vCard.Longitude. These correspond with

the GEO property of the specification. Usage seems to be
very rare but is implemented here for completeness.

- Added vCard.Photos, a collection of vCardPhoto objects.

A photo can be referenced as a URL or specified directly
with a bitmap or byte array.

- Added vCard.RevisionDate (nullable date). This contains the

last revision date of the vCard. The library does not
update this value when you make changes; you need to set
the revision date yourself. This maps to the REV property
of the specification.

- Renamed vCardPhone.Subtype to vCardPhone.PhoneType in order to

be consistent with the naming conventions used elsewhere in
the library.

And much more.

------------------------------------------------------------------------
2007-05-14: Version 0.2
------------------------------------------------------------------------

vCard Format/Specification Changes:

- Added support for the KEY property, which is used to embed

a certificate in the vCard. Only the BASE64 encoding, used by
Microsoft Outlook and many PIMs, is supported. Thanks for
Martin Meraner

- Added support for the MAILER property. This property identifies

the software that generated the vCard; it is described in
section 2.4.3 of the vCard 2.1 specification.

- Added support for the SOURCE vCard property. This property

identifies the URI of a directory that provided information
 for the vCard contents (e.g., an LDAP URL).

- Added support for the UID property. This property is a string

that uniquely identifies the vCard in relation to other vCards.
There is no standard but typical ID strings might be URLs,
GUIDs, etc.

- Added support for the X-WAB-GENDER extended property. This

property identifies the gender of the contact; it may not be
supported elsewhere and therefore should be used with care.
It is an extended property used by Microsoft Outlook.

- Added support for the ROLE property. This property describes

the role of the person at his/her organization, e.g. Programmer
or Executive, etc.

Class Library API Changes:

- Added the standard .NET constructors to the vCardException class.

- Added a unit testing project (designed for NUnit).
- Added vCardCertificate
- Added vCardCertificateCollection
- Added vCardDeliveryLabel
- Added vCardDeliveryLabelType
- Added vCardGender
- Added vCardSource
- Added vCardSourceCollection
- Added vCardValueType
- Fixed and expanded inline and XML comments.
- Fixed typo of vCardPhone.IsCelluar to vCardPhone.IsCellular.

------------------------------------------------------------------------
2007-03-07: Version 0.1
------------------------------------------------------------------------

Initial release on www.thoughtproject.com/Libraries/vCards/