Saving and Serialization

This group contains functions for saving and serializing either drawings or individual objects. More...

Detailed Description

This group contains functions for saving and serializing either drawings or individual objects.

Functions
GlgBoolean	GlgSaveObject (GlgObject object, char *filename)
	Saves an object to a file. More...
GlgBoolean	GlgSerialize (GlgObject object, GlgBoolean(*func)(void *data, GlgLong size, void *user_data), void *user_data)
	Saves a GLG object into a data stream by invoking a custom serialization callback, which can be used to implement custom save methods. More...
void *	GlgSerializeFull (GlgObject object, GlgLong *size)
	Saves a GLG object into a raw memory block. More...

Function Documentation

GlgSaveObject()

GlgBoolean GlgSaveObject	(	GlgObject	object,
		char *	filename
	)

Saves an object to a file.

Parameters

object	The object to be saved; it may be any GLG object.
filename	The file to save the object to.

Returns

False if the file is not accessible for writing, True if the object was successfully saved.

This function saves the specified object and all its subsidiary objects to a file. A GLG object of any type may be saved in this fashion and later loaded using GlgLoadObject. The GlgSaveFormat global configuration resource described the Appendices chapter of the GLG Programming Reference Manual may be used to modify save type.

For applications that load a drawing, modify it and save if back to a file, the drawing should be loaded using GlgLoadObject instead of GlgLoadWidgetFromFile. GlgLoadWidgetFromFile extracts the $Widget viewport from the loaded drawing, discarding the rest of the drawing, while GlgLoadObject returns an object that represents the whole drawing.

Using GlgSaveObject to save a viewport loaded with GlgLoadWidgetFromFile will result in a loss of information contained in the discarded part of the drawing, such as the type of the coordinate system used to display the viewport, which will make it difficult to load and edit the drawing in the Graphics Builder. The following example demonstrates the proper technique:

GlgObject drawing = GlgLoadObject( "drawing.g" );
GlgObject viewport = GlgLoadWidgetFromObject( drawing ); // Extract $Widget viewport.
 
... // Code that modifies the drawing using the <i>viewport</i> object ID.
 
GlgSaveObject( drawing, "new_drawing.g" );

GlgSerialize()

GlgBoolean GlgSerialize	(	GlgObject	object,
		GlgBoolean(*)(void *data, GlgLong size, void *user_data)	func,
		void *	user_data
	)

Saves a GLG object into a data stream by invoking a custom serialization callback, which can be used to implement custom save methods.

Parameters

object	The object to be saved; it may be any GLG object.
func	A custom serialization callback function that will be invoked to save the object. The function will be invoked repeatedly with the data and size parameters supplying the pointer to the data that needs to be saved and the size of the data in bytes. The user_data parameter will supply user_data passed to the GlgSerialize function. At the end of the serialization process, the function will be invoked with data=NULL and size=-1 to flush any remaining data. The function must return True to continue, or False to abort serialization, in which case GlgSerialize will return False as well.
user_data	The user data to be passed to the callback function.

Returns

Success or failure status.

GlgSerializeFull()

void* GlgSerializeFull	(	GlgObject	object,
		GlgLong *	size
	)

Saves a GLG object into a raw memory block.

Parameters

object	The object to be saved; it may be any GLG object.
size	A pointer to a variable that will be set to the size of the returned memory block.

Returns

A pointer to the memory block containing the saved object image, or NULL on error.

The size of the returned memory block is returned via the size parameter. The memory should be freed using GlgFree when it is no longer used.