001: /* ====================================================================
002: Licensed to the Apache Software Foundation (ASF) under one or more
003: contributor license agreements. See the NOTICE file distributed with
004: this work for additional information regarding copyright ownership.
005: The ASF licenses this file to You under the Apache License, Version 2.0
006: (the "License"); you may not use this file except in compliance with
007: the License. You may obtain a copy of the License at
008:
009: http://www.apache.org/licenses/LICENSE-2.0
010:
011: Unless required by applicable law or agreed to in writing, software
012: distributed under the License is distributed on an "AS IS" BASIS,
013: WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: See the License for the specific language governing permissions and
015: limitations under the License.
016: ==================================================================== */
017:
018: package org.apache.poi.hpsf;
019:
020: import java.util.Collections;
021: import java.util.HashMap;
022: import java.util.Map;
023:
024: /**
025: * <p>The <em>Variant</em> types as defined by Microsoft's COM. I
026: * found this information in <a
027: * href="http://www.marin.clara.net/COM/variant_type_definitions.htm">
028: * http://www.marin.clara.net/COM/variant_type_definitions.htm</a>.</p>
029: *
030: * <p>In the variant types descriptions the following shortcuts are
031: * used: <strong> [V]</strong> - may appear in a VARIANT,
032: * <strong>[T]</strong> - may appear in a TYPEDESC,
033: * <strong>[P]</strong> - may appear in an OLE property set,
034: * <strong>[S]</strong> - may appear in a Safe Array.</p>
035: *
036: * @author Rainer Klute (klute@rainer-klute.de)
037: * @version $Id: Variant.java 489730 2006-12-22 19:18:16Z bayard $
038: * @since 2002-02-09
039: */
040: public class Variant {
041:
042: /**
043: * <p>[V][P] Nothing, i.e. not a single byte of data.</p>
044: */
045: public static final int VT_EMPTY = 0;
046:
047: /**
048: * <p>[V][P] SQL style Null.</p>
049: */
050: public static final int VT_NULL = 1;
051:
052: /**
053: * <p>[V][T][P][S] 2 byte signed int.</p>
054: */
055: public static final int VT_I2 = 2;
056:
057: /**
058: * <p>[V][T][P][S] 4 byte signed int.</p>
059: */
060: public static final int VT_I4 = 3;
061:
062: /**
063: * <p>[V][T][P][S] 4 byte real.</p>
064: */
065: public static final int VT_R4 = 4;
066:
067: /**
068: * <p>[V][T][P][S] 8 byte real.</p>
069: */
070: public static final int VT_R8 = 5;
071:
072: /**
073: * <p>[V][T][P][S] currency. <span style="background-color:
074: * #ffff00">How long is this? How is it to be
075: * interpreted?</span></p>
076: */
077: public static final int VT_CY = 6;
078:
079: /**
080: * <p>[V][T][P][S] date. <span style="background-color:
081: * #ffff00">How long is this? How is it to be
082: * interpreted?</span></p>
083: */
084: public static final int VT_DATE = 7;
085:
086: /**
087: * <p>[V][T][P][S] OLE Automation string. <span
088: * style="background-color: #ffff00">How long is this? How is it
089: * to be interpreted?</span></p>
090: */
091: public static final int VT_BSTR = 8;
092:
093: /**
094: * <p>[V][T][P][S] IDispatch *. <span style="background-color:
095: * #ffff00">How long is this? How is it to be
096: * interpreted?</span></p>
097: */
098: public static final int VT_DISPATCH = 9;
099:
100: /**
101: * <p>[V][T][S] SCODE. <span style="background-color: #ffff00">How
102: * long is this? How is it to be interpreted?</span></p>
103: */
104: public static final int VT_ERROR = 10;
105:
106: /**
107: * <p>[V][T][P][S] True=-1, False=0.</p>
108: */
109: public static final int VT_BOOL = 11;
110:
111: /**
112: * <p>[V][T][P][S] VARIANT *. <span style="background-color:
113: * #ffff00">How long is this? How is it to be
114: * interpreted?</span></p>
115: */
116: public static final int VT_VARIANT = 12;
117:
118: /**
119: * <p>[V][T][S] IUnknown *. <span style="background-color:
120: * #ffff00">How long is this? How is it to be
121: * interpreted?</span></p>
122: */
123: public static final int VT_UNKNOWN = 13;
124:
125: /**
126: * <p>[V][T][S] 16 byte fixed point.</p>
127: */
128: public static final int VT_DECIMAL = 14;
129:
130: /**
131: * <p>[T] signed char.</p>
132: */
133: public static final int VT_I1 = 16;
134:
135: /**
136: * <p>[V][T][P][S] unsigned char.</p>
137: */
138: public static final int VT_UI1 = 17;
139:
140: /**
141: * <p>[T][P] unsigned short.</p>
142: */
143: public static final int VT_UI2 = 18;
144:
145: /**
146: * <p>[T][P] unsigned int.</p>
147: */
148: public static final int VT_UI4 = 19;
149:
150: /**
151: * <p>[T][P] signed 64-bit int.</p>
152: */
153: public static final int VT_I8 = 20;
154:
155: /**
156: * <p>[T][P] unsigned 64-bit int.</p>
157: */
158: public static final int VT_UI8 = 21;
159:
160: /**
161: * <p>[T] signed machine int.</p>
162: */
163: public static final int VT_INT = 22;
164:
165: /**
166: * <p>[T] unsigned machine int.</p>
167: */
168: public static final int VT_UINT = 23;
169:
170: /**
171: * <p>[T] C style void.</p>
172: */
173: public static final int VT_VOID = 24;
174:
175: /**
176: * <p>[T] Standard return type. <span style="background-color:
177: * #ffff00">How long is this? How is it to be
178: * interpreted?</span></p>
179: */
180: public static final int VT_HRESULT = 25;
181:
182: /**
183: * <p>[T] pointer type. <span style="background-color:
184: * #ffff00">How long is this? How is it to be
185: * interpreted?</span></p>
186: */
187: public static final int VT_PTR = 26;
188:
189: /**
190: * <p>[T] (use VT_ARRAY in VARIANT).</p>
191: */
192: public static final int VT_SAFEARRAY = 27;
193:
194: /**
195: * <p>[T] C style array. <span style="background-color:
196: * #ffff00">How long is this? How is it to be
197: * interpreted?</span></p>
198: */
199: public static final int VT_CARRAY = 28;
200:
201: /**
202: * <p>[T] user defined type. <span style="background-color:
203: * #ffff00">How long is this? How is it to be
204: * interpreted?</span></p>
205: */
206: public static final int VT_USERDEFINED = 29;
207:
208: /**
209: * <p>[T][P] null terminated string.</p>
210: */
211: public static final int VT_LPSTR = 30;
212:
213: /**
214: * <p>[T][P] wide (Unicode) null terminated string.</p>
215: */
216: public static final int VT_LPWSTR = 31;
217:
218: /**
219: * <p>[P] FILETIME. The FILETIME structure holds a date and time
220: * associated with a file. The structure identifies a 64-bit
221: * integer specifying the number of 100-nanosecond intervals which
222: * have passed since January 1, 1601. This 64-bit value is split
223: * into the two dwords stored in the structure.</p>
224: */
225: public static final int VT_FILETIME = 64;
226:
227: /**
228: * <p>[P] Length prefixed bytes.</p>
229: */
230: public static final int VT_BLOB = 65;
231:
232: /**
233: * <p>[P] Name of the stream follows.</p>
234: */
235: public static final int VT_STREAM = 66;
236:
237: /**
238: * <p>[P] Name of the storage follows.</p>
239: */
240: public static final int VT_STORAGE = 67;
241:
242: /**
243: * <p>[P] Stream contains an object. <span
244: * style="background-color: #ffff00"> How long is this? How is it
245: * to be interpreted?</span></p>
246: */
247: public static final int VT_STREAMED_OBJECT = 68;
248:
249: /**
250: * <p>[P] Storage contains an object. <span
251: * style="background-color: #ffff00"> How long is this? How is it
252: * to be interpreted?</span></p>
253: */
254: public static final int VT_STORED_OBJECT = 69;
255:
256: /**
257: * <p>[P] Blob contains an object. <span style="background-color:
258: * #ffff00">How long is this? How is it to be
259: * interpreted?</span></p>
260: */
261: public static final int VT_BLOB_OBJECT = 70;
262:
263: /**
264: * <p>[P] Clipboard format. <span style="background-color:
265: * #ffff00">How long is this? How is it to be
266: * interpreted?</span></p>
267: */
268: public static final int VT_CF = 71;
269:
270: /**
271: * <p>[P] A Class ID.</p>
272: *
273: * <p>It consists of a 32 bit unsigned integer indicating the size
274: * of the structure, a 32 bit signed integer indicating (Clipboard
275: * Format Tag) indicating the type of data that it contains, and
276: * then a byte array containing the data.</p>
277: *
278: * <p>The valid Clipboard Format Tags are:</p>
279: *
280: * <ul>
281: * <li>{@link Thumbnail#CFTAG_WINDOWS}</li>
282: * <li>{@link Thumbnail#CFTAG_MACINTOSH}</li>
283: * <li>{@link Thumbnail#CFTAG_NODATA}</li>
284: * <li>{@link Thumbnail#CFTAG_FMTID}</li>
285: * </ul>
286: *
287: * <pre>typedef struct tagCLIPDATA {
288: * // cbSize is the size of the buffer pointed to
289: * // by pClipData, plus sizeof(ulClipFmt)
290: * ULONG cbSize;
291: * long ulClipFmt;
292: * BYTE* pClipData;
293: * } CLIPDATA;</pre>
294: *
295: * <p>See <a
296: * href="msdn.microsoft.com/library/en-us/com/stgrstrc_0uwk.asp"
297: * target="_blank">
298: * msdn.microsoft.com/library/en-us/com/stgrstrc_0uwk.asp</a>.</p>
299: */
300: public static final int VT_CLSID = 72;
301:
302: /**
303: * <p>[P] simple counted array. <span style="background-color:
304: * #ffff00">How long is this? How is it to be
305: * interpreted?</span></p>
306: */
307: public static final int VT_VECTOR = 0x1000;
308:
309: /**
310: * <p>[V] SAFEARRAY*. <span style="background-color: #ffff00">How
311: * long is this? How is it to be interpreted?</span></p>
312: */
313: public static final int VT_ARRAY = 0x2000;
314:
315: /**
316: * <p>[V] void* for local use. <span style="background-color:
317: * #ffff00">How long is this? How is it to be
318: * interpreted?</span></p>
319: */
320: public static final int VT_BYREF = 0x4000;
321:
322: /**
323: * <p>FIXME (3): Document this!</p>
324: */
325: public static final int VT_RESERVED = 0x8000;
326:
327: /**
328: * <p>FIXME (3): Document this!</p>
329: */
330: public static final int VT_ILLEGAL = 0xFFFF;
331:
332: /**
333: * <p>FIXME (3): Document this!</p>
334: */
335: public static final int VT_ILLEGALMASKED = 0xFFF;
336:
337: /**
338: * <p>FIXME (3): Document this!</p>
339: */
340: public static final int VT_TYPEMASK = 0xFFF;
341:
342: /**
343: * <p>Maps the numbers denoting the variant types to their corresponding
344: * variant type names.</p>
345: */
346: private static Map numberToName;
347:
348: private static Map numberToLength;
349:
350: /**
351: * <p>Denotes a variant type with a length that is unknown to HPSF yet.</p>
352: */
353: public static final Integer LENGTH_UNKNOWN = new Integer(-2);
354:
355: /**
356: * <p>Denotes a variant type with a variable length.</p>
357: */
358: public static final Integer LENGTH_VARIABLE = new Integer(-1);
359:
360: /**
361: * <p>Denotes a variant type with a length of 0 bytes.</p>
362: */
363: public static final Integer LENGTH_0 = new Integer(0);
364:
365: /**
366: * <p>Denotes a variant type with a length of 2 bytes.</p>
367: */
368: public static final Integer LENGTH_2 = new Integer(2);
369:
370: /**
371: * <p>Denotes a variant type with a length of 4 bytes.</p>
372: */
373: public static final Integer LENGTH_4 = new Integer(4);
374:
375: /**
376: * <p>Denotes a variant type with a length of 8 bytes.</p>
377: */
378: public static final Integer LENGTH_8 = new Integer(8);
379:
380: static {
381: /* Initialize the number-to-name map: */
382: Map tm1 = new HashMap();
383: tm1.put(new Long(0), "VT_EMPTY");
384: tm1.put(new Long(1), "VT_NULL");
385: tm1.put(new Long(2), "VT_I2");
386: tm1.put(new Long(3), "VT_I4");
387: tm1.put(new Long(4), "VT_R4");
388: tm1.put(new Long(5), "VT_R8");
389: tm1.put(new Long(6), "VT_CY");
390: tm1.put(new Long(7), "VT_DATE");
391: tm1.put(new Long(8), "VT_BSTR");
392: tm1.put(new Long(9), "VT_DISPATCH");
393: tm1.put(new Long(10), "VT_ERROR");
394: tm1.put(new Long(11), "VT_BOOL");
395: tm1.put(new Long(12), "VT_VARIANT");
396: tm1.put(new Long(13), "VT_UNKNOWN");
397: tm1.put(new Long(14), "VT_DECIMAL");
398: tm1.put(new Long(16), "VT_I1");
399: tm1.put(new Long(17), "VT_UI1");
400: tm1.put(new Long(18), "VT_UI2");
401: tm1.put(new Long(19), "VT_UI4");
402: tm1.put(new Long(20), "VT_I8");
403: tm1.put(new Long(21), "VT_UI8");
404: tm1.put(new Long(22), "VT_INT");
405: tm1.put(new Long(23), "VT_UINT");
406: tm1.put(new Long(24), "VT_VOID");
407: tm1.put(new Long(25), "VT_HRESULT");
408: tm1.put(new Long(26), "VT_PTR");
409: tm1.put(new Long(27), "VT_SAFEARRAY");
410: tm1.put(new Long(28), "VT_CARRAY");
411: tm1.put(new Long(29), "VT_USERDEFINED");
412: tm1.put(new Long(30), "VT_LPSTR");
413: tm1.put(new Long(31), "VT_LPWSTR");
414: tm1.put(new Long(64), "VT_FILETIME");
415: tm1.put(new Long(65), "VT_BLOB");
416: tm1.put(new Long(66), "VT_STREAM");
417: tm1.put(new Long(67), "VT_STORAGE");
418: tm1.put(new Long(68), "VT_STREAMED_OBJECT");
419: tm1.put(new Long(69), "VT_STORED_OBJECT");
420: tm1.put(new Long(70), "VT_BLOB_OBJECT");
421: tm1.put(new Long(71), "VT_CF");
422: tm1.put(new Long(72), "VT_CLSID");
423: Map tm2 = new HashMap(tm1.size(), 1.0F);
424: tm2.putAll(tm1);
425: numberToName = Collections.unmodifiableMap(tm2);
426:
427: /* Initialize the number-to-length map: */
428: tm1.clear();
429: tm1.put(new Long(0), LENGTH_0);
430: tm1.put(new Long(1), LENGTH_UNKNOWN);
431: tm1.put(new Long(2), LENGTH_2);
432: tm1.put(new Long(3), LENGTH_4);
433: tm1.put(new Long(4), LENGTH_4);
434: tm1.put(new Long(5), LENGTH_8);
435: tm1.put(new Long(6), LENGTH_UNKNOWN);
436: tm1.put(new Long(7), LENGTH_UNKNOWN);
437: tm1.put(new Long(8), LENGTH_UNKNOWN);
438: tm1.put(new Long(9), LENGTH_UNKNOWN);
439: tm1.put(new Long(10), LENGTH_UNKNOWN);
440: tm1.put(new Long(11), LENGTH_UNKNOWN);
441: tm1.put(new Long(12), LENGTH_UNKNOWN);
442: tm1.put(new Long(13), LENGTH_UNKNOWN);
443: tm1.put(new Long(14), LENGTH_UNKNOWN);
444: tm1.put(new Long(16), LENGTH_UNKNOWN);
445: tm1.put(new Long(17), LENGTH_UNKNOWN);
446: tm1.put(new Long(18), LENGTH_UNKNOWN);
447: tm1.put(new Long(19), LENGTH_UNKNOWN);
448: tm1.put(new Long(20), LENGTH_UNKNOWN);
449: tm1.put(new Long(21), LENGTH_UNKNOWN);
450: tm1.put(new Long(22), LENGTH_UNKNOWN);
451: tm1.put(new Long(23), LENGTH_UNKNOWN);
452: tm1.put(new Long(24), LENGTH_UNKNOWN);
453: tm1.put(new Long(25), LENGTH_UNKNOWN);
454: tm1.put(new Long(26), LENGTH_UNKNOWN);
455: tm1.put(new Long(27), LENGTH_UNKNOWN);
456: tm1.put(new Long(28), LENGTH_UNKNOWN);
457: tm1.put(new Long(29), LENGTH_UNKNOWN);
458: tm1.put(new Long(30), LENGTH_VARIABLE);
459: tm1.put(new Long(31), LENGTH_UNKNOWN);
460: tm1.put(new Long(64), LENGTH_8);
461: tm1.put(new Long(65), LENGTH_UNKNOWN);
462: tm1.put(new Long(66), LENGTH_UNKNOWN);
463: tm1.put(new Long(67), LENGTH_UNKNOWN);
464: tm1.put(new Long(68), LENGTH_UNKNOWN);
465: tm1.put(new Long(69), LENGTH_UNKNOWN);
466: tm1.put(new Long(70), LENGTH_UNKNOWN);
467: tm1.put(new Long(71), LENGTH_UNKNOWN);
468: tm1.put(new Long(72), LENGTH_UNKNOWN);
469: tm2 = new HashMap(tm1.size(), 1.0F);
470: tm2.putAll(tm1);
471: numberToLength = Collections.unmodifiableMap(tm2);
472: }
473:
474: /**
475: * <p>Returns the variant type name associated with a variant type
476: * number.</p>
477: *
478: * @param variantType The variant type number
479: * @return The variant type name or the string "unknown variant type"
480: */
481: public static String getVariantName(final long variantType) {
482: final String name = (String) numberToName.get(new Long(
483: variantType));
484: return name != null ? name : "unknown variant type";
485: }
486:
487: /**
488: * <p>Returns a variant type's length.</p>
489: *
490: * @param variantType The variant type number
491: * @return The length of the variant type's data in bytes. If the length is
492: * variable, i.e. the length of a string, -1 is returned. If HPSF does not
493: * know the length, -2 is returned. The latter usually indicates an
494: * unsupported variant type.
495: */
496: public static int getVariantLength(final long variantType) {
497: final Long key = new Long((int) variantType);
498: final Long length = (Long) numberToLength.get(key);
499: if (length == null)
500: return -2;
501: return length.intValue();
502: }
503:
504: }
|