Edit

Share via

IInkDisp::Save method (msinkaut.h)

  • Article

Converts the ink to the specified InkPersistenceFormat, saves the ink by using the specified InkPersistenceCompressionMode, and returns the binary data in an array of bytes.

Syntax

HRESULT Save(
  [in, optional] InkPersistenceFormat          PersistenceFormat,
  [in, optional] InkPersistenceCompressionMode CompressionMode,
  [out, retval]  VARIANT                       *Data
);

Parameters

[in, optional] PersistenceFormat

Optional. Sets one of the InkPersistenceFormat values that indicates the format of the persisted ink. The default value is InkSerializedFormat.

Name Description
InkSerializedFormat
 Ink is persisted using ink serialized format (ISF).

This is the most compact persistent representation of ink. It can be embedded within a binary document format or placed directly on the Clipboard. This is the default value.
Base64InkSerializedFormat
 Ink is persisted by encoding the ISF as a base64 stream.

This format is provided so that ink can be encoded directly in an Extensible Markup Language (XML) or HTML file.
Gif
 Ink is persisted by using a Graphics Interchange Format (GIF) file that contains ISF as metadata that is embedded within the file.

This allows ink to be viewed in applications that are not ink-enabled and maintain its full ink fidelity when it returns to an ink-enabled application. This format is ideal when transporting ink content within an HTML file and making it usable by ink-enabled and ink-unaware applications.
Base64Gif
 Ink is persisted by using a base64 encoded fortified.

This GIFformat is provided when ink is to be encoded directly in an XML or HTML file with later conversion into an image. A possible use of this would be in an XML format that is generated to contain all ink information and used as a way to generate HTML through Extensible Stylesheet Language Transformations (XSLT).

[in, optional] CompressionMode

Optional. One of the InkPersistenceCompressionMode values that specifies the compression mode of the persisted ink. The default value is IPCM_Default.

Name Description
IPCM_Default
 Is used when the best tradeoff between save-time and storage for the typical application is needed.
IPCM_MaximumCompression
 Is used when minimizing storage space is more important than how fast the ink is saved.
IPCM_NoCompression
 Is used when save-time is more important than the amount of storage space used and when compatibility between versions is important.

[out, retval] Data

When this method returns, contains the byte array that contains the persisted ink.

For more information about the VARIANT structure, see Using the COM Library.

Return value

This method can return one of these values.

Return code Description
S_OK
 Success.
E_POINTER
 A parameter contained an invalid pointer.
E_INK_EXCEPTION
 An exception occurred inside the method.
E_INVALIDARG
 Invalid compression mode.
E_OUTOFMEMORY
 Cannot allocate byte array.
E_UNEXPECTED
 Occurs if you attempt to save an empty Ink object in GIF format.

Remarks

Attempting to save an empty InkDisp object in GIF format generates an error.

Note  When calling the Save method with an InkPersistenceFormat value of Base64InkSerializedFormat, the return value is a NULL -terminated byte array. To write the saved ink to an XML file, first remove the last byte from the array before converting the array to 8-bit Unicode Transformation Format (UTF-8) encoded string.
 

Requirements

Requirement Value
Minimum supported client Windows XP Tablet PC Edition [desktop apps only]
Minimum supported server None supported
Target Platform Windows
Header msinkaut.h
Library InkObj.dll

See also

IInkDisp

InkDisp Class

InkPersistenceCompressionMode Enumeration

InkPersistenceFormat Enumeration

Load Method