forked from harold4/Thought.vCards
-
Notifications
You must be signed in to change notification settings - Fork 1
/
ReadMe.txt
188 lines (134 loc) · 8.22 KB
/
ReadMe.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
vCard Class Library for .NET (Version 0.4; LGPL license)
Copyright (c) 2007-2009 David Pinch * http://www.thoughtproject.com/Libraries/vCard/
Introduction
This is a simple library for manipulating vCards. A vCard is used to exchange
contact information (e.g. to import into Microsoft Outlook or download from
the web into a suitable PIM application). All code is released under the LGPL
for free use and with full permission to use with commercial software.
General Design:
(a) The vCard object model is separated from the various vCard file formats.
You can manipulate contact information, photos, and other properties in the
standard way you would expect from a .NET class library.
(b) Almost all vCard properties can exist multiple times in a vCard file.
However, some judgement is used when determining whether a property
should be implemented as a collection or a singular property. For
example, it is possible to have multiple formatted names, each in a
different language. The need for this functionality is very rare
and therefore the formatted name property is implemented as a string
property rather than collection of "formatted name" objects.
On the other hand, multiple email addresses are common. Email addresses
are stored in a collection. Nevertheless, feel free to request changes
if you believe singular property should be converted to a collection.
(c) The vCardReader and vCardWriter classes are abstract classes that
define the interfaces for reading and writing vCard formats. This
version of the library supplies vCardStandardReader and vCardStandardWriter,
which implement the vCard 2.1 format specification.
A future version will include support for Jabber, RDF and hCard formats.
If you want to help evolve the library, adding support for those
formats will be appreciated.
(d) Example usage (in VB.NET; the library itself is in C#):
Dim card As New vCard()
card.GivenName = "David"
card.FamilyName = "Pinch"
Dim photo as New vCardPhoto( _
"http://www.thoughtproject.com/Common/me.jpg")
card.Photos.Add(photo)
Dim writer as vCardStandardWriter = New vCardStandardWriter()
writer.EmbedWebPhotos = true
writer.Write(card, "c:\davepinch.vcf")
Folders (directories):
.\ (root)
file_id.diz ............................. Description in FILE_ID.DIZ format*
license.txt ............................. LGPL license text
pad_file.xml ............................ Description in PAD XML format*
readme.txt .............................. This file.
roadmap.txt ............................. Plans for the next version
* These two files are provided for the convenience of file distribution
networks and shareware/freeware sites. They contain information that can
be extracted by special computer programs. Developers can ignore or
delete the files.
.\Solution\
The Solution folder contains a Visual Studio 2008 solution for building the
vCard class library. A unit test project (nUnit) is also provided.
.\Reference\
Copies of the vCard RFC (Request for Comments) documents. Other resources
and technical information will be placed into this folder in the future
releases. Documents in this folder may be copyrighted products under
licenses that allow redistribution (but not affiliated with the author).
.\Help\
A help project for Sandcastle Help File Builder. See Readme.Text in the
folder for instructions on building your own documentation. An sample
help file (CHM) has been compiled for your convenience.
.\Samples\
Samples demonstrating use the library.
Current Status
This is version 0.4 of the library. It implements a substantial portion of the
vCard standard. Future efforts will focus on compatible formats like
hCard and RDF. However, the library is still treated as beta status.
Please do not use on production systems unless you are confident with the
degree of functionality currently implemented.
ADR .......................... Delivery address
BDAY ......................... Birthdate (partial)
CATEGORIES ................... Category names / keywords
CLASS ........................ Access classification
EMAIL ........................ Email address
FN ........................... Formatted name
GEO .......................... Geographical coordinates
KEY .......................... Certificate key
LABEL ........................ Delivery label
MAILER ....................... Mailer software name
N ............................ Name
NAME ......................... Display name of the vCard
NICKNAME ..................... Nickname
NOTE ......................... Note/Comment
ORG .......................... Organization
PHOTO ........................ Personal photos
PRODID ....................... Product name/version
REV .......................... Revision date
ROLE ......................... Role/profession
SOURCE ....................... Directory source
TEL .......................... Telephone number
TITLE ........................ Job title
TZ ........................... Time zone
UID .......................... Unique ID
URL .......................... Web site
X-WAB-GENDER ................. Gender (Outlook Extension)
Known issues to be fixed in a future release (before version 1.0):
- Preferred addresses and labels not marked as preferred
Credits
Thanks for Martin Meraner for providing testing assistance and helping with
the certificate implementation. Thanks to Bill Lunney for assisting with
photo/imaging support. Thanks to Richard Bennett for testing. Thanks
to Robbie Paplin for helping with image (photo) support. Thanks to Karsten
Januszeski for pushing me to update the library and eventually move to
CodePlex.
Support and Downloads
The author is happy to assist people using the library. Please make sure you have
downloaded the latest copy of the code from the following web site:
http://www.thoughtproject.com/Libraries/vCard/
You can reach the author at the following:
David Pinch
http://www.linkedin.com/in/davepinch
When sending code changes or bug reports, let me know if you want me to list your
home page or some other personal statement. This is the least I can do. People
who contribute source code and other materials will also be credited in the
copyrights. You should be comfortable with the LGPL open source license before
sharing any code, though!
Linked-In users are welcome to send an invitation/connection request. Be sure
to mention this library (or any library on thoughtproject.com) in your invitation.
Please submit vCard files that are not correctly parsed by the library.
License and Copyrights
vCard Class Library for .NET (version 0.4 -- alpha)
Copyright (C) 2007 David Pinch ([email protected]) and contributors
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA