001 /*
002 * Copyright (c) OSGi Alliance (2002, 2008). All Rights Reserved.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016 package org.osgi.service.upnp;
017
018 import java.io.IOException;
019 import java.io.InputStream;
020
021 /**
022 * A UPnP icon representation.
023 *
024 * Each UPnP device can contain zero or more icons.
025 *
026 * @version $Revision: 5673 $
027 */
028 public interface UPnPIcon {
029 /**
030 * Returns the MIME type of the icon.
031 *
032 * This method returns the format in which the icon graphics, read from the
033 * <code>InputStream</code> object obtained by the <code>getInputStream()</code>
034 * method, is encoded.
035 * <p>
036 * The format of the returned string is in accordance to RFC2046. A list of
037 * valid MIME types is maintained by the <a
038 * href="http://www.iana.org/assignments/media-types/">IANA</a>.
039 * <p>
040 * Typical values returned include: "image/jpeg" or "image/gif"
041 *
042 * @return The MIME type of the encoded icon.
043 */
044 String getMimeType();
045
046 /**
047 * Returns the width of the icon in pixels.
048 *
049 * If the actual width of the icon is unknown, -1 is returned.
050 *
051 * @return The width in pixels, or -1 if unknown.
052 */
053 int getWidth();
054
055 /**
056 * Returns the height of the icon in pixels.
057 *
058 * If the actual height of the icon is unknown, -1 is returned.
059 *
060 * @return The height in pixels, or -1 if unknown.
061 */
062 int getHeight();
063
064 /**
065 * Returns the size of the icon in bytes.
066 *
067 * This method returns the number of bytes of the icon available to read
068 * from the <code>InputStream</code> object obtained by the
069 * <code>getInputStream()</code> method. If the actual size can not be
070 * determined, -1 is returned.
071 *
072 * @return The icon size in bytes, or -1 if the size is unknown.
073 */
074 int getSize();
075
076 /**
077 * Returns the color depth of the icon in bits.
078 *
079 * @return The color depth in bits. If the actual color depth of the icon is
080 * unknown, -1 is returned.
081 */
082 int getDepth();
083
084 /**
085 * Returns an <code>InputStream</code> object for the icon data.
086 *
087 * The <code>InputStream</code> object provides a way for a client to read the
088 * actual icon graphics data. The number of bytes available from this
089 * <code>InputStream</code> object can be determined via the
090 * <code>getSize()</code> method. The format of the data encoded can be
091 * determined by the MIME type availble via the <code>getMimeType()</code>
092 * method.
093 *
094 * @return An InputStream to read the icon graphics data from.
095 * @throws IOException If the <code>InputStream</code> cannot be returned.
096 * @see UPnPIcon#getMimeType()
097 */
098 InputStream getInputStream() throws IOException;
099 }