001package ezvcard.property;
002
003import java.io.IOException;
004import java.io.InputStream;
005import java.nio.file.Path;
006
007import ezvcard.parameter.ImageType;
008
009/*
010 Copyright (c) 2012-2023, 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 * <p>
040 * Defines a photo, such as the person's portrait.
041 * </p>
042 * 
043 * <p>
044 * <b>Code sample (creating)</b>
045 * </p>
046 * 
047 * <pre class="brush:java">
048 * VCard vcard = new VCard();
049 * 
050 * //URL
051 * Photo photo = new Photo("http://www.mywebsite.com/my-photo.jpg", ImageType.JPEG);
052 * vcard.addPhoto(photo);
053 * 
054 * //binary data
055 * byte data[] = ...
056 * photo = new Photo(data, ImageType.JPEG);
057 * vcard.addPhoto(photo);
058 * </pre>
059 * 
060 * <p>
061 * <b>Code sample (retrieving)</b>
062 * </p>
063 * 
064 * <pre class="brush:java">
065 * VCard vcard = ...
066 * for (Photo photo : vcard.getPhotos()) {
067 *   PhotoType contentType = photo.getContentType(); //e.g. "image/jpeg"
068 * 
069 *   String url = photo.getUrl();
070 *   if (url != null) {
071 *     //property value is a URL
072 *     continue;
073 *   }
074 *   
075 *   byte[] data = photo.getData();
076 *   if (data != null) {
077 *     //property value is binary data
078 *     continue;
079 *   }
080 * }
081 * </pre>
082 * 
083 * <p>
084 * <b>Property name:</b> {@code PHOTO}
085 * </p>
086 * <p>
087 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
088 * </p>
089 * @author Michael Angstadt
090 * @see <a href="http://tools.ietf.org/html/rfc6350#page-30">RFC 6350 p.30</a>
091 * @see <a href="http://tools.ietf.org/html/rfc2426#page-10">RFC 2426 p.10</a>
092 * @see <a href="http://www.imc.org/pdi/vcard-21.doc">vCard 2.1 p.10</a>
093 */
094public class Photo extends ImageProperty {
095        /**
096         * Creates a photo property.
097         * @param url the URL to the photo
098         * @param type the content type (e.g. JPEG)
099         */
100        public Photo(String url, ImageType type) {
101                super(url, type);
102        }
103
104        /**
105         * Creates a photo property.
106         * @param data the binary data of the photo
107         * @param type the content type (e.g. JPEG)
108         */
109        public Photo(byte[] data, ImageType type) {
110                super(data, type);
111        }
112
113        /**
114         * Creates a photo property.
115         * @param in an input stream to the binary data (will be closed)
116         * @param type the content type (e.g. JPEG)
117         * @throws IOException if there's a problem reading from the input stream
118         */
119        public Photo(InputStream in, ImageType type) throws IOException {
120                super(in, type);
121        }
122
123        /**
124         * Creates a photo property.
125         * @param file the image file
126         * @param type the content type (e.g. JPEG)
127         * @throws IOException if there's a problem reading from the file
128         */
129        public Photo(Path file, ImageType type) throws IOException {
130                super(file, type);
131        }
132
133        /**
134         * Copy constructor.
135         * @param original the property to make a copy of
136         */
137        public Photo(Photo original) {
138                super(original);
139        }
140
141        @Override
142        public Photo copy() {
143                return new Photo(this);
144        }
145}