org.apache.poi.hpsf.Thumbnail Maven / Gradle / Ivy
Show all versions of apache-poi Show documentation
/* ====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
==================================================================== */
package org.apache.poi.hpsf;
import org.apache.poi.util.IOUtils;
import org.apache.poi.util.LittleEndian;
/**
* Class to manipulate data in the Clipboard Variant ({@link
* Variant#VT_CF VT_CF}) format.
*
* @see SummaryInformation#getThumbnail()
* @see Clipboard Operations
*/
public final class Thumbnail {
/**
* Offset in bytes where the Clipboard Format Tag starts in the
* byte[] returned by {@link
* SummaryInformation#getThumbnail()}
*/
public static final int OFFSET_CFTAG = 4;
/**
* Offset in bytes where the Clipboard Format starts in the
* byte[] returned by {@link
* SummaryInformation#getThumbnail()}
*
* This is only valid if the Clipboard Format Tag is {@link
* #CFTAG_WINDOWS}
*/
public static final int OFFSET_CF = 8;
/**
* Offset in bytes where the Windows Metafile (WMF) image data
* starts in the byte[] returned by {@link
* SummaryInformation#getThumbnail()}
*
* There is only WMF data at this point in the
* byte[] if the Clipboard Format Tag is {@link
* #CFTAG_WINDOWS} and the Clipboard Format is {@link
* #CF_METAFILEPICT}.
*
* Note: The byte[] that starts at
* OFFSET_WMFDATA and ends at
* getThumbnail().length - 1 forms a complete WMF
* image. It can be saved to disk with a .wmf file
* type and read using a WMF-capable image viewer.
*/
public static final int OFFSET_WMFDATA = 20;
/**
* Clipboard Format Tag - Windows clipboard format
*
* A DWORD indicating a built-in Windows clipboard
* format value
*/
public static final int CFTAG_WINDOWS = -1;
/**
* Clipboard Format Tag - Macintosh clipboard format
*
* A DWORD indicating a Macintosh clipboard format
* value
*/
public static final int CFTAG_MACINTOSH = -2;
/**
* Clipboard Format Tag - Format ID
*
* A GUID containing a format identifier (FMTID). This is
* rarely used.
*/
public static final int CFTAG_FMTID = -3;
/**
* Clipboard Format Tag - No Data
*
* A DWORD indicating No data. This is rarely
* used.
*/
public static final int CFTAG_NODATA = 0;
/**
* Clipboard Format - Windows metafile format. This is the
* recommended way to store thumbnails in Property Streams.
*
* Note: This is not the same format used in
* regular WMF images. The clipboard version of this format has an
* extra clipboard-specific header.
*/
public static final int CF_METAFILEPICT = 3;
/**
* Clipboard Format - Device Independent Bitmap
*/
public static final int CF_DIB = 8;
/**
* Clipboard Format - Enhanced Windows metafile format
*/
public static final int CF_ENHMETAFILE = 14;
/**
* Clipboard Format - Bitmap
*/
public static final int CF_BITMAP = 2;
//arbitrarily selected; may need to increase
private static final int DEFAULT_MAX_RECORD_LENGTH = 1_000_000;
private static int MAX_RECORD_LENGTH = DEFAULT_MAX_RECORD_LENGTH;
/**
* A byte[] to hold a thumbnail image in ({@link
* Variant#VT_CF VT_CF}) format.
*/
private byte[] _thumbnailData;
/**
* @param length the max record length allowed for SubRecord
*/
public static void setMaxRecordLength(int length) {
MAX_RECORD_LENGTH = length;
}
/**
* @return the max record length allowed for SubRecord
*/
public static int getMaxRecordLength() {
return MAX_RECORD_LENGTH;
}
/**
* Default Constructor. If you use it then one you'll have to add
* the thumbnail byte[] from {@link
* SummaryInformation#getThumbnail()} to do any useful
* manipulations, otherwise you'll get a
* NullPointerException.
*/
public Thumbnail()
{
super();
}
/**
* Creates a Thumbnail instance and initializes
* with the specified image bytes.
*
* @param thumbnailData The thumbnail data
*/
public Thumbnail(final byte[] thumbnailData)
{
this._thumbnailData = thumbnailData;
}
/**
* Returns the thumbnail as a byte[] in {@link
* Variant#VT_CF VT_CF} format.
*
* @return The thumbnail value
* @see SummaryInformation#getThumbnail()
*/
public byte[] getThumbnail()
{
return _thumbnailData;
}
/**
* Sets the Thumbnail's underlying byte[] in
* {@link Variant#VT_CF VT_CF} format.
*
* @param thumbnail The new thumbnail value
* @see SummaryInformation#getThumbnail()
*/
public void setThumbnail(final byte[] thumbnail)
{
this._thumbnailData = thumbnail;
}
/**
* Returns an int representing the Clipboard
* Format Tag
*
* Possible return values are:
*
* - {@link #CFTAG_WINDOWS CFTAG_WINDOWS}
* - {@link #CFTAG_MACINTOSH CFTAG_MACINTOSH}
* - {@link #CFTAG_FMTID CFTAG_FMTID}
* - {@link #CFTAG_NODATA CFTAG_NODATA}
*
*
* @return A flag indicating the Clipboard Format Tag
*/
public long getClipboardFormatTag()
{
return (long) LittleEndian.getInt(getThumbnail(),
OFFSET_CFTAG);
}
/**
* Returns an int representing the Clipboard
* Format
*
* Will throw an exception if the Thumbnail's Clipboard Format
* Tag is not {@link Thumbnail#CFTAG_WINDOWS CFTAG_WINDOWS}.
*
* Possible return values are:
*
*
* - {@link #CF_METAFILEPICT CF_METAFILEPICT}
* - {@link #CF_DIB CF_DIB}
* - {@link #CF_ENHMETAFILE CF_ENHMETAFILE}
* - {@link #CF_BITMAP CF_BITMAP}
*
*
* @return a flag indicating the Clipboard Format
* @throws HPSFException if the Thumbnail isn't CFTAG_WINDOWS
*/
public long getClipboardFormat() throws HPSFException
{
if (!(getClipboardFormatTag() == CFTAG_WINDOWS))
throw new HPSFException("Clipboard Format Tag of Thumbnail must " +
"be CFTAG_WINDOWS.");
return LittleEndian.getInt(getThumbnail(), OFFSET_CF);
}
/**
* Returns the Thumbnail as a byte[] of WMF data
* if the Thumbnail's Clipboard Format Tag is {@link
* #CFTAG_WINDOWS CFTAG_WINDOWS} and its Clipboard Format is
* {@link #CF_METAFILEPICT CF_METAFILEPICT}
This
* byte[] is in the traditional WMF file, not the
* clipboard-specific version with special headers.
*
* See http://www.wvware.com/caolan/ora-wmf.html
* for more information on the WMF image format.
*
* @return A WMF image of the Thumbnail
* @throws HPSFException if the Thumbnail isn't CFTAG_WINDOWS and
* CF_METAFILEPICT
*/
public byte[] getThumbnailAsWMF() throws HPSFException
{
if (!(getClipboardFormatTag() == CFTAG_WINDOWS))
throw new HPSFException("Clipboard Format Tag of Thumbnail must " +
"be CFTAG_WINDOWS.");
if (!(getClipboardFormat() == CF_METAFILEPICT)) {
throw new HPSFException("Clipboard Format of Thumbnail must " +
"be CF_METAFILEPICT.");
}
byte[] thumbnail = getThumbnail();
return IOUtils.safelyClone(thumbnail, OFFSET_WMFDATA, thumbnail.length - OFFSET_WMFDATA, MAX_RECORD_LENGTH);
}
}