Bonobo API Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# BonoboPersistStream

## Name

BonoboPersistStream -- Interface for anything that can save / load itself from a Bonobo stream.

## Synopsis

    struct      BonoboPersistStream;
    void        (*BonoboPersistStreamIOFn)      (BonoboPersistStream *ps,
                                                 const Bonobo_Stream stream,
                                                 Bonobo_Persist_ContentType type,
                                                 void *closure,
                                                 CORBA_Environment *ev);
    CORBA_long  (*BonoboPersistStreamMaxFn)     (BonoboPersistStream *ps,
                                                 void *closure,
                                                 CORBA_Environment *ev);
    Bonobo_Persist_ContentTypeList* (*BonoboPersistStreamTypesFn)
                                                (BonoboPersistStream *ps,
                                                 void *closure,
                                                 CORBA_Environment *ev);
    typedef     BonoboPersistStreamClass;
    void        bonobo_persist_stream_set_dirty (BonoboPersistStream *ps,
                                                 gboolean dirty);
    BonoboPersistStream* bonobo_persist_stream_new
                                                (BonoboPersistStreamIOFn load_fn,
                                                 BonoboPersistStreamIOFn save_fn,
                                                 BonoboPersistStreamMaxFn max_fn,
                                                 BonoboPersistStreamTypesFn types_fn,
                                                 void *closure);
    BonoboPersistStream* bonobo_persist_stream_construct
                                                (BonoboPersistStream *ps,
                                                 BonoboPersistStreamIOFn load_fn,
                                                 BonoboPersistStreamIOFn save_fn,
                                                 BonoboPersistStreamMaxFn max_fn,
                                                 BonoboPersistStreamTypesFn types_fn,
                                                 void *closure);

## Description

The PersistStream interface is the interface to use for all new components that are able to load and save themselves to a stream. It should be associated with any BonoboEmbeddable for use by the container in creating a compound document.

This interface works by connecting callbacks to the methods, in a somewhat deprecated fashion, it is probably better nowadays to simply sub-class the BonoboXObject and override the epv methods. Either way, after all the caveats here is an example use:

Example 1. Implementing the PersistStream callbacks

    static void
    load_from_stream (BonoboPersistStream        *ps,
                      const Bonobo_Stream         stream,
                      Bonobo_Persist_ContentType  type,
                      void                       *closure,
                      CORBA_Environment          *ev)
    {
    	EogImageData *image_data = closure;

    	g_warning ("Load content from stream of type 's'", type);
    }

    static gint
    save_to_stream (BonoboPersistStream        *ps,
                    const Bonobo_Stream         stream,
                    Bonobo_Persist_ContentType  type,
                    void                       *closure,
                    CORBA_Environment          *ev)
    {
    	EogImageData *image_data = closure;

    	g_warning ("Save content to stream with type 's'", type);
    }

    static Bonobo_Persist_ContentTypeList *
    get_supported_types (BonoboPersistStream *ps,
                         void                *closure,
                         CORBA_Environment   *ev)
    {
    	return bonobo_persist_generate_content_types (
    		2, "text/plain", "text/html");
    }

Having implemented the callbacks we then have to register them and aggregate the interface to our object:

Example 2. Aggregating a new PersistStream

    EogImageData *
    eog_image_data_construct (EogImageData *image_data)
    {
    	BonoboObject        *retval;
    	BonoboPersistStream *ps;

    	ps = bonobo_persist_stream_new (
    		load_from_stream, save_to_stream,
    		get_supported_types, NULL,
    		image_data);

    	if (ps == NULL) {
    		bonobo_object_unref (BONOBO_OBJECT (image_data));
    		return NULL;
    	}

    	bonobo_object_add_interface (BONOBO_OBJECT (image_data),
    				     BONOBO_OBJECT (ps));

    	return image_data;
    }

## Details

### struct BonoboPersistStream

    struct BonoboPersistStream;

### BonoboPersistStreamIOFn ()

    void        (*BonoboPersistStreamIOFn)      (BonoboPersistStream *ps,
                                                 const Bonobo_Stream stream,
                                                 Bonobo_Persist_ContentType type,
                                                 void *closure,
                                                 CORBA_Environment *ev);

`ps` : |
`stream` : |
`type` : |
`closure` : |
`ev` : |

### BonoboPersistStreamMaxFn ()

    CORBA_long  (*BonoboPersistStreamMaxFn)     (BonoboPersistStream *ps,
                                                 void *closure,
                                                 CORBA_Environment *ev);

`ps` : |
`closure` : |
`ev` : |
Returns : |

### BonoboPersistStreamTypesFn ()

    Bonobo_Persist_ContentTypeList* (*BonoboPersistStreamTypesFn)
                                                (BonoboPersistStream *ps,
                                                 void *closure,
                                                 CORBA_Environment *ev);

`ps` : |
`closure` : |
`ev` : |
Returns : |

### BonoboPersistStreamClass

    typedef struct {
    	BonoboPersistClass parent_class;

    	POA_Bonobo_PersistStream__epv epv;

    	/* methods */
    	void       (*load)         (BonoboPersistStream        *ps,
    				    Bonobo_Stream              stream,
    				    Bonobo_Persist_ContentType type,
    				    CORBA_Environment          *ev);
    	void       (*save)         (BonoboPersistStream        *ps,
    				    Bonobo_Stream              stream,
    				    Bonobo_Persist_ContentType type,
    				    CORBA_Environment          *ev);
    	CORBA_long (*get_size_max) (BonoboPersistStream *ps,
    				    CORBA_Environment   *ev);
    	Bonobo_Persist_ContentTypeList * (*get_content_types) (BonoboPersistStream *ps,
    							       CORBA_Environment   *ev);

    } BonoboPersistStreamClass;

### bonobo_persist_stream_set_dirty ()

    void        bonobo_persist_stream_set_dirty (BonoboPersistStream *ps,
                                                 gboolean dirty);

This routine sets the dirty bit for the PersistStream object.

`ps` : | A BonoboPersistStream object
`dirty` : | A boolean value representing whether the object is dirty or not

### bonobo_persist_stream_new ()

    BonoboPersistStream* bonobo_persist_stream_new
                                                (BonoboPersistStreamIOFn load_fn,
                                                 BonoboPersistStreamIOFn save_fn,
                                                 BonoboPersistStreamMaxFn max_fn,
                                                 BonoboPersistStreamTypesFn types_fn,
                                                 void *closure);

Creates a new BonoboPersistStream object. The various operations for the object are performed by the provided callback functions, which are passed `closure` when they are invoked. If any callback is `NULL`, the corresponding operation is performed by the class load and save routines.

`load_fn` : | Loading routine
`save_fn` : | Saving routine
`max_fn` : | get_max_size routine
`types_fn` : | get_content_types routine
`closure` : | Data passed to IO routines.
Returns : | the newly-created BonoboPersistStream object.

### bonobo_persist_stream_construct ()

    BonoboPersistStream* bonobo_persist_stream_construct
                                                (BonoboPersistStream *ps,
                                                 BonoboPersistStreamIOFn load_fn,
                                                 BonoboPersistStreamIOFn save_fn,
                                                 BonoboPersistStreamMaxFn max_fn,
                                                 BonoboPersistStreamTypesFn types_fn,
                                                 void *closure);

Initializes the BonoboPersistStream object. The load and save operations for the object are performed by the provided `load_fn` and `save_fn` callback functions, which are passed `closure` when they are invoked. If either `load_fn` or `save_fn` is `NULL`, the corresponding operation is performed by the class load and save routines.

`ps` : | A BonoboPersistStream object
`load_fn` : | Loading routine
`save_fn` : | Saving routine
`max_fn` : |
`types_fn` : |
`closure` : | Data passed to IO routines.
Returns : | The initialized BonoboPersistStream object.

<<< Previous Page | Home | Up | Next Page >>>
BonoboPersistFile | BonoboProgressiveDataSink