GsfClipData
3
GSF Library

# 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);

## 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 {
    	GObject object;

    	GsfClipDataPrivate *priv;
    } 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