GsfClipData

GsfClipData — Object to hold clipboard data from a VT_CF section

Synopsis




enum        GsfClipFormat;
enum        GsfClipFormatWindows;
            GsfClipData;
            GsfClipDataClass;
GsfClipData* gsf_clip_data_new              (GsfClipFormat format,
                                             GsfBlob *data_blob);
GsfClipFormat gsf_clip_data_get_format      (GsfClipData *clip_data);
GsfBlob*    gsf_clip_data_get_data_blob     (GsfClipData *clip_data);
GsfClipFormatWindows gsf_clip_data_get_windows_clipboard_format
                                            (GsfClipData *clip_data,
                                             GError **error);
gconstpointer gsf_clip_data_peek_real_data  (GsfClipData *clip_data,
                                             gsize *ret_size,
                                             GError **error);


Object Hierarchy


  GObject
   +----GsfClipData

Description

OLE2 files may contain clipboard data in the VT_CF property of the metadata in a SummaryInfo section. This data is used, among other things, to represent a thumbnail or pre-rendered version of the data in the file. GsfClipData is an object that holds such clipboard data.

You can get a GsfClipData object from the GValue returned by gsf_doc_prop_get_val(), after you have done gsf_doc_meta_data_lookup (meta_data, GSF_META_NAME_THUMBNAIL). The resulting GsfClipData object, if it exists, contains the thumbnail data. In turn, the thumbnail data may be in different formats, as specified by the GsfClipFormat enumeration.

Internally, GsfClipData stores the thumbnail data plus any extra information in a GsfBlob object. GsfClipData provides a convenience function, gsf_clip_data_peek_real_data(), to extract the thumbnail data directly. If you need to use the raw binary data instead of the data specific to the thumbnail, you can use gsf_clip_data_get_data_blob() to get the GsfBlob object and handle it yourself.

Details

enum GsfClipFormat

typedef enum {
	GSF_CLIP_FORMAT_WINDOWS_CLIPBOARD = -1,
	GSF_CLIP_FORMAT_MACINTOSH_CLIPBOARD = -2,
	GSF_CLIP_FORMAT_GUID = -3,
	GSF_CLIP_FORMAT_NO_DATA = 0,
	GSF_CLIP_FORMAT_CLIPBOARD_FORMAT_NAME = 1, /* in the file it's actually any positive integer */
	GSF_CLIP_FORMAT_UNKNOWN /* this is our own value for unknown types or invalid data */
} GsfClipFormat;

A GsfClipData stores all its thumbnail data and associated information in an internal GsfBlob object. The GsfClipFormat enumeration represents the possible formats for this data blob.

GSF_CLIP_FORMAT_WINDOWS_CLIPBOARD The thumbnail data is stored in Windows clipboard format. The particular sub-format can be in any of the values in the GsfClipFormatWindows enumeration. When a GsfClipData is in GSF_CLIP_FORMAT_WINDOWS_CLIPBOARD, you can use gsf_clip_data_get_windows_clipboard_format() to get the sub-format in which the data is actually stored.
GSF_CLIP_FORMAT_MACINTOSH_CLIPBOARD The thumbnail data is stored in Macintosh clipboard format, usually PICT.
GSF_CLIP_FORMAT_GUID The thumbnail data contains a GUID specifying the OLE component which can be used to render it. Please refer to the OLE2 format documentation for details.
GSF_CLIP_FORMAT_NO_DATA There is no thumbnail data.
GSF_CLIP_FORMAT_CLIPBOARD_FORMAT_NAME The thumbnail data contains a null-terminated string with a Windows clipboard format name. Please refer to the OLE2 format documentation for details.
GSF_CLIP_FORMAT_UNKNOWN The thumbnail data is in an unknown format, but is nevertheless stored in a GsfBlob.

enum GsfClipFormatWindows

typedef enum {
	GSF_CLIP_FORMAT_WINDOWS_ERROR = -1,		/* our own value */
	GSF_CLIP_FORMAT_WINDOWS_UNKNOWN = -2,		/* our own value */
	GSF_CLIP_FORMAT_WINDOWS_METAFILE = 3,		/* CF_METAFILEPICT */
	GSF_CLIP_FORMAT_WINDOWS_DIB = 8,		/* CF_DIB */
	GSF_CLIP_FORMAT_WINDOWS_ENHANCED_METAFILE = 14	/* CF_ENHMETAFILE */
} GsfClipFormatWindows;

When a GsfClipData is in GSF_CLIP_FORMAT_WINDOWS_CLIPBOARD format, it can be in any of the subformats specified by the GsfClipFormatWindows enumeration. Use gsf_clip_data_get_windows_clipboard_format() to determine this sub-format.

For all of these values, the gsf_clip_data_peek_real_data() function lets you access the data directly.

GSF_CLIP_FORMAT_WINDOWS_ERROR The OLE file is probably corrupt.
GSF_CLIP_FORMAT_WINDOWS_UNKNOWN The specific clipboard format is unknown to libgsf.
GSF_CLIP_FORMAT_WINDOWS_METAFILE The data is in Windows Metafile format. While OLE files store extra header data in this case, the gsf_clip_data_peek_real_data() function will let you access the WMF data directly, and it will ignore the extra header bytes.
GSF_CLIP_FORMAT_WINDOWS_DIB The data is in Windows Device-Independent Bitmap format.
GSF_CLIP_FORMAT_WINDOWS_ENHANCED_METAFILE The data is in Windows Enhanced Metaflie format.

GsfClipData

typedef struct _GsfClipData GsfClipData;

Object used to represent a VT_CF property in the OLE stream.


GsfClipDataClass

typedef struct {
	GObjectClass parent_class;
} GsfClipDataClass;


gsf_clip_data_new ()

GsfClipData* gsf_clip_data_new              (GsfClipFormat format,
                                             GsfBlob *data_blob);

Creates a new GsfClipData object. This function acquires a reference to the data_blob, so you should unref the blob on your own if you no longer need it directly.

format : Format for the data inside the data_blob
data_blob : Object which holds the binary contents for the GsfClipData
Returns : A newly-created GsfClipData.

gsf_clip_data_get_format ()

GsfClipFormat gsf_clip_data_get_format      (GsfClipData *clip_data);

Queries the clipboard data format of a GsfClipData. The format refers to the data blob inside the clip_data; use gsf_clip_data_get_data_blob() to get that data blob.

clip_data : A GsfClipData.
Returns : The format in which the GsfClipData's data blob is stored.

gsf_clip_data_get_data_blob ()

GsfBlob*    gsf_clip_data_get_data_blob     (GsfClipData *clip_data);

Queries the data blob that actually stores a GsfClipData's binary data.

clip_data : A GsfClipData.
Returns : A new reference to the GsfBlob that stores this clip_data's binary data. You must use g_object_unref() to dispose of that data blob when you are done with it.

gsf_clip_data_get_windows_clipboard_format ()

GsfClipFormatWindows gsf_clip_data_get_windows_clipboard_format
                                            (GsfClipData *clip_data,
                                             GError **error);

Queries the Windows clipboard data format for a GsfClipData. The clip_data must have been created with GSF_CLIP_FORMAT_WINDOWS_CLIPBOARD.

clip_data : A GsfClipData.
error : Location to store error, or NULL
Returns : A GsfClipFormatWindows value. Possible errors: GSF_ERROR_INVALID_DATA if the data blob in the clip_data is smaller than it should be; in this case GSF_CLIP_FORMAT_WINDOWS_ERROR will be returned.

gsf_clip_data_peek_real_data ()

gconstpointer gsf_clip_data_peek_real_data  (GsfClipData *clip_data,
                                             gsize *ret_size,
                                             GError **error);

Queries a pointer directly to the clipboard data of a GsfClipData. The resulting pointer is not necessarily the same data pointer that was passed to gsf_blob_new() prior to creating the clip_data. For example, if the data is in GSF_CLIP_FORMAT_WINDOWS_CLIPBOARD format, then it will have extra header bytes in front of the actual metafile data. This function will skip over those header bytes if necessary and return a pointer to the "real" data.

clip_data : A GsfClipData.
ret_size : Location to return the size of the returned data buffer.
error : Location to store error, or NULL.
Returns : Pointer to the real clipboard data. The size in bytes of this buffer is returned in the ret_size argument.

See Also

GsfBlob, GsfDocMetaData