001 package ezvcard.property;
002
003 import java.io.File;
004 import java.io.IOException;
005 import java.io.InputStream;
006
007 import ezvcard.parameter.ImageType;
008
009 /*
010 Copyright (c) 2013, Michael Angstadt
011 All rights reserved.
012
013 Redistribution and use in source and binary forms, with or without
014 modification, are permitted provided that the following conditions are met:
015
016 1. Redistributions of source code must retain the above copyright notice, this
017 list of conditions and the following disclaimer.
018 2. Redistributions in binary form must reproduce the above copyright notice,
019 this list of conditions and the following disclaimer in the documentation
020 and/or other materials provided with the distribution.
021
022 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
023 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
024 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
025 DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
026 ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
027 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
028 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
029 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
030 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
031 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
032
033 The views and conclusions contained in the software and documentation are those
034 of the authors and should not be interpreted as representing official policies,
035 either expressed or implied, of the FreeBSD Project.
036 */
037
038 /**
039 * A photo attached to the vCard (such as a portrait of the person).
040 *
041 * <p>
042 * <b>Adding a photo</b>
043 * </p>
044 *
045 * <pre class="brush:java">
046 * VCard vcard = new VCard();
047 *
048 * //URL
049 * Photo photo = new Photo("http://www.mywebsite.com/mugshot.jpg", ImageType.JPEG);
050 * vcard.addPhoto(photo);
051 *
052 * //binary data
053 * byte data[] = ...
054 * photo = new Photo(data, ImageType.JPEG);
055 * vcard.addPhoto(photo);
056 *
057 * //if "ImageType" does not have the pre-defined constant that you need, then create a new instance
058 * //arg 1: the value of the 2.1/3.0 TYPE parameter
059 * //arg 2: the value to use for the 4.0 MEDIATYPE parameter and for 4.0 data URIs
060 * //arg 3: the file extension of the data type (optional)
061 * ImageKeyTypeParameter param = new ImageType("bmp", "image/x-ms-bmp", "bmp");
062 * photo = new Photo("http://www.mywebsite.com/mugshot.bmp", param);
063 * vcard.addPhoto(photo);
064 * </pre>
065 *
066 * <p>
067 * <b>Getting the photos</b>
068 * </p>
069 *
070 * <pre class="brush:java">
071 * VCard vcard = ...
072 *
073 * int fileCount = 0;
074 * for (Photo photo : vcard.getPhotos()){
075 * //the photo will have either a URL or a binary data
076 * if (photo.getData() == null){
077 * System.out.println("Photo URL: " + photo.getUrl());
078 * } else {
079 * ImageType type = photo.getContentType();
080 *
081 * if (type == null) {
082 * //the vCard may not have any content type data associated with the photo
083 * System.out.println("Saving a photo file...");
084 * } else {
085 * System.out.println("Saving a \"" + type.getMediaType() + "\" file...");
086 * }
087 *
088 * String folder;
089 * if (type == ImageType.JPEG){ //it is safe to use "==" instead of "equals()"
090 * folder = "photos";
091 * } else {
092 * folder = "images";
093 * }
094 *
095 * byte data[] = photo.getData();
096 * String filename = "photo" + fileCount;
097 * if (type != null && type.getExtension() != null){
098 * filename += "." + type.getExtension();
099 * }
100 * OutputStream out = new FileOutputStream(new File(folder, filename));
101 * out.write(data);
102 * out.close();
103 * fileCount++;
104 * }
105 * }
106 * </pre>
107 *
108 * <p>
109 * <b>Property name:</b> {@code PHOTO}
110 * </p>
111 * <p>
112 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
113 * </p>
114 * @author Michael Angstadt
115 */
116 public class Photo extends ImageProperty {
117 /**
118 * Creates a photo property.
119 * @param url the URL to the photo
120 * @param type the content type (e.g. JPEG)
121 */
122 public Photo(String url, ImageType type) {
123 super(url, type);
124 }
125
126 /**
127 * Creates a photo property.
128 * @param data the binary data of the photo
129 * @param type the content type (e.g. JPEG)
130 */
131 public Photo(byte[] data, ImageType type) {
132 super(data, type);
133 }
134
135 /**
136 * Creates a photo property.
137 * @param in an input stream to the binary data (will be closed)
138 * @param type the content type (e.g. JPEG)
139 * @throws IOException if there's a problem reading from the input stream
140 */
141 public Photo(InputStream in, ImageType type) throws IOException {
142 super(in, type);
143 }
144
145 /**
146 * Creates a photo property.
147 * @param file the image file
148 * @param type the content type (e.g. JPEG)
149 * @throws IOException if there's a problem reading from the file
150 */
151 public Photo(File file, ImageType type) throws IOException {
152 super(file, type);
153 }
154 }