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.SoundType;
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 sound to attach to the vCard, such as a pronunciation of the person's name.
040 *
041 * <p>
042 * <b>Adding a sound</b>
043 * </p>
044 *
045 * <pre class="brush:java">
046 * VCard vcard = new VCard();
047 *
048 * //URL
049 * Sound sound = new Sound("http://www.mywebsite.com/myname.ogg", SoundType.OGG);
050 * vcard.addSound(sound);
051 *
052 * //binary data
053 * byte data[] = ...
054 * sound = new Sound(data, SoundType.OGG);
055 * vcard.addSound(sound);
056 *
057 * //if "SoundType" 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 * SoundType param = new SoundType("wav", "audio/wav", "wav");
062 * sound = new Sound("http://www.mywebsite.com/myname.wav", SoundType.WAV);
063 * vcard.addSound(sound);
064 * </pre>
065 *
066 * <p>
067 * <b>Getting the sounds</b>
068 * </p>
069 *
070 * <pre class="brush:java">
071 * VCard vcard = ...
072 *
073 * int fileCount = 0;
074 * for (Sound sound : vcard.getSounds()){
075 * //the sound will have either a URL or a binary data
076 * if (sound.getData() == null){
077 * System.out.println("Sound URL: " + sound.getUrl());
078 * } else {
079 * SoundType type = sound.getContentType();
080 *
081 * if (type == null) {
082 * //the vCard may not have any content type data associated with the sound
083 * System.out.println("Saving a sound file...");
084 * } else {
085 * System.out.println("Saving a \"" + type.getMediaType() + "\" file...");
086 * }
087 *
088 * String folder;
089 * if (type == SoundType.OGG){ //it is safe to use "==" instead of "equals()"
090 * folder = "ogg-files";
091 * } else {
092 * folder = "sound-files";
093 * }
094 *
095 * byte data[] = sound.getData();
096 * String filename = "sound" + 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 SOUND}
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 Sound extends BinaryProperty<SoundType> {
117 /**
118 * Creates a sound property.
119 * @param url the URL to the sound file
120 * @param type the content type (e.g. OGG)
121 */
122 public Sound(String url, SoundType type) {
123 super(url, type);
124 }
125
126 /**
127 * Creates a sound property.
128 * @param data the binary data of the sound file
129 * @param type the content type (e.g. OGG)
130 */
131 public Sound(byte[] data, SoundType type) {
132 super(data, type);
133 }
134
135 /**
136 * Creates a sound property.
137 * @param in an input stream to the binary data (will be closed)
138 * @param type the content type (e.g. OGG)
139 * @throws IOException if there's a problem reading from the input stream
140 */
141 public Sound(InputStream in, SoundType type) throws IOException {
142 super(in, type);
143 }
144
145 /**
146 * Creates a sound property.
147 * @param file the sound file
148 * @param type the content type (e.g. OGG)
149 * @throws IOException if there's a problem reading from the file
150 */
151 public Sound(File file, SoundType type) throws IOException {
152 super(file, type);
153 }
154
155 @Override
156 public String getLanguage() {
157 return super.getLanguage();
158 }
159
160 @Override
161 public void setLanguage(String language) {
162 super.setLanguage(language);
163 }
164 }