diff options
Diffstat (limited to 'doc/public/html/bindings-streams.html')
| -rw-r--r-- | doc/public/html/bindings-streams.html | 99 |
1 files changed, 99 insertions, 0 deletions
diff --git a/doc/public/html/bindings-streams.html b/doc/public/html/bindings-streams.html new file mode 100644 index 0000000..4001c16 --- /dev/null +++ b/doc/public/html/bindings-streams.html @@ -0,0 +1,99 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Streams and File I/O</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.65.1"> +<link rel="home" href="index.html" title="Cairo: A Vector Graphics Library"> +<link rel="up" href="language-bindings.html" title="Appendix A. Creating a language binding for cairo"> +<link rel="previous" href="bindings-overloading.html" title="Overloading and optional arguments"> +<link rel="next" href="bindings-errors.html" title="Error handling"> +<meta name="generator" content="GTK-Doc V1.4 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +<link rel="part" href="pt01.html" title="Part I. Tutorial"> +<link rel="part" href="pt02.html" title="Part II. Reference"> +<link rel="index" href="ix01.html" title="Index"> +<link rel="appendix" href="language-bindings.html" title="Appendix A. Creating a language binding for cairo"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle"> +<td><a accesskey="p" href="bindings-overloading.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td> +<td><a accesskey="u" href="language-bindings.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td> +<th width="100%" align="center">Cairo: A Vector Graphics Library</th> +<td><a accesskey="n" href="bindings-errors.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td> +</tr></table> +<div class="sect1" lang="en"> +<div class="titlepage"> +<div><div><h2 class="title" style="clear: both"> +<a name="bindings-streams"></a>Streams and File I/O</h2></div></div> +<div></div> +</div> +<p> + 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: + </p> +<pre class="programlisting"> +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);</pre> +<p> + 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: + </p> +<pre class="programlisting"> +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; +</pre> +<p> + 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 + <tt class="methodname">createFromPNG()</tt> 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 + <i class="parameter"><tt>closure</tt></i>, and then rethrow it once + the function returns. + </p> +<i><span class="remark"> + I'm not sure how to handle this for + <tt class="function">cairo_pdf_surface_create_for_callback()</tt>. + Other than keep a “exception to rethrow” thread-specific + variable + that is checked after <span class="emphasis"><em>every</em></span> call to a Cairo + function. + </span></i> +</div> +<table class="navigation" width="100%" summary="Navigation footer" cellpadding="2" cellspacing="0"><tr valign="middle"> +<td align="left"><a accesskey="p" href="bindings-overloading.html"><b><< Overloading and optional arguments</b></a></td> +<td align="right"><a accesskey="n" href="bindings-errors.html"><b>Error handling >></b></a></td> +</tr></table> +</body> +</html> |