Streams and File I/O: Cairo: A Vector Graphics Library

-Streams and File I/O

- Various places in the cairo API deal with reading and writing - data, whether from and to files, or to other sources and - destinations. In these cases, what is typically provided in the - C API is a simple version that just takes a filename, and a - complex version that takes a callback function. - An example is the PNG handling functions: -

-cairo_surface_t *
-cairo_image_surface_create_from_png (const char	*filename);
-
-cairo_surface_t *
-cairo_image_surface_create_from_png_stream (cairo_read_func_t read_func,
-					    void             *closure);
-
-cairo_status_t
-cairo_surface_write_to_png (cairo_surface_t	*surface,
-			    const char		*filename);
-
-cairo_status_t
-cairo_surface_write_to_png_stream (cairo_surface_t	*surface,
-				   cairo_write_func_t	write_func,
-				   void			*closure);

- The expectation is that the filename version will be mapped - literally in the language binding, but the callback version - will be mapped to a version that takes a language stream - object. For example, in Java, the four functions above - might be mapped to: -

-static public ImageSurface createFromPNG (String filename) throws IOException;
-static public ImageSurface createFromPNG (InputStream stream) throws IOException;
-public void writeToPNG (String filename) throws IOException;
-public void writeToPNG (OutputStream stream) throws IOException;
-

- In many cases, it will be better to - implement the filename version internally - using the stream version, rather than building it on top of the - filename version in C. The reason for this is that will - naturally give a more standard handling of file errors for - the language, as seen in the above Java example, where - createFromPNG() is marked as raising - an exception. Propagating exceptions from inside the callback - function to the caller will pose a challenge to the language - binding implementor, since an exception must not propagate - through the Cairo code. A technique that will be useful in - some cases is to catch the exception in the callback, - store the exception object inside a structure pointed to by - closure, and then rethrow it once - the function returns. -

- I'm not sure how to handle this for - cairo_pdf_surface_create_for_stream(). - Other than keep a “exception to rethrow” thread-specific - variable - that is checked after every call to a Cairo - function. -