Mercurial > repos > rliterman > csp2

diff CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/share/gtk-doc/html/cairo/bindings-streams.html @ 68:5028fdace37b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 16:23:26 -0400
parents
children
line wrap: on
line diff
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/share/gtk-doc/html/cairo/bindings-streams.html	Tue Mar 18 16:23:26 2025 -0400
@@ -0,0 +1,91 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<title>Streams and File I/O: Cairo: A Vector Graphics Library</title>
+<meta name="generator" content="DocBook XSL Stylesheets V1.79.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="prev" 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.27 (XML mode)">
+<link rel="stylesheet" href="style.css" type="text/css">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
+<td width="100%" align="left" class="shortcuts"></td>
+<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
+<td><a accesskey="u" href="language-bindings.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
+<td><a accesskey="p" href="bindings-overloading.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
+<td><a accesskey="n" href="bindings-errors.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
+</tr></table>
+<div class="sect1">
+<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>
+<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
+      <code class="methodname">createFromPNG()</code> 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
+      <em class="parameter"><code>closure</code></em>, and then rethrow it once
+      the function returns.
+    </p>
+<p class="remark"><em><span class="remark">
+      I'm not sure how to handle this for
+      <a class="link" href="cairo-PDF-Surfaces.html#cairo-pdf-surface-create-for-stream" title="cairo_pdf_surface_create_for_stream ()"><code class="function">cairo_pdf_surface_create_for_stream()</code></a>.
+      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></em></p>
+</div>
+<div class="footer">
+<hr>Generated by GTK-Doc V1.27</div>
+</body>
+</html>
\ No newline at end of file