Mercurial > repos > rliterman > csp2
comparison CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/share/gtk-doc/html/cairo/bindings-streams.html @ 68:5028fdace37b
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
| author | jpayne |
|---|---|
| date | Tue, 18 Mar 2025 16:23:26 -0400 |
| parents | |
| children |
comparison
equal
deleted
inserted
replaced
| 67:0e9998148a16 | 68:5028fdace37b |
|---|---|
| 1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> | |
| 2 <html> | |
| 3 <head> | |
| 4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> | |
| 5 <title>Streams and File I/O: Cairo: A Vector Graphics Library</title> | |
| 6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> | |
| 7 <link rel="home" href="index.html" title="Cairo: A Vector Graphics Library"> | |
| 8 <link rel="up" href="language-bindings.html" title="Appendix A. Creating a language binding for cairo"> | |
| 9 <link rel="prev" href="bindings-overloading.html" title="Overloading and optional arguments"> | |
| 10 <link rel="next" href="bindings-errors.html" title="Error handling"> | |
| 11 <meta name="generator" content="GTK-Doc V1.27 (XML mode)"> | |
| 12 <link rel="stylesheet" href="style.css" type="text/css"> | |
| 13 </head> | |
| 14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> | |
| 15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle"> | |
| 16 <td width="100%" align="left" class="shortcuts"></td> | |
| 17 <td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> | |
| 18 <td><a accesskey="u" href="language-bindings.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> | |
| 19 <td><a accesskey="p" href="bindings-overloading.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> | |
| 20 <td><a accesskey="n" href="bindings-errors.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> | |
| 21 </tr></table> | |
| 22 <div class="sect1"> | |
| 23 <div class="titlepage"><div><div><h2 class="title" style="clear: both"> | |
| 24 <a name="bindings-streams"></a>Streams and File I/O</h2></div></div></div> | |
| 25 <p> | |
| 26 Various places in the cairo API deal with reading and writing | |
| 27 data, whether from and to files, or to other sources and | |
| 28 destinations. In these cases, what is typically provided in the | |
| 29 C API is a simple version that just takes a filename, and a | |
| 30 complex version that takes a callback function. | |
| 31 An example is the PNG handling functions: | |
| 32 </p> | |
| 33 <pre class="programlisting"> | |
| 34 cairo_surface_t * | |
| 35 cairo_image_surface_create_from_png (const char *filename); | |
| 36 | |
| 37 cairo_surface_t * | |
| 38 cairo_image_surface_create_from_png_stream (cairo_read_func_t read_func, | |
| 39 void *closure); | |
| 40 | |
| 41 cairo_status_t | |
| 42 cairo_surface_write_to_png (cairo_surface_t *surface, | |
| 43 const char *filename); | |
| 44 | |
| 45 cairo_status_t | |
| 46 cairo_surface_write_to_png_stream (cairo_surface_t *surface, | |
| 47 cairo_write_func_t write_func, | |
| 48 void *closure);</pre> | |
| 49 <p> | |
| 50 The expectation is that the filename version will be mapped | |
| 51 literally in the language binding, but the callback version | |
| 52 will be mapped to a version that takes a language stream | |
| 53 object. For example, in Java, the four functions above | |
| 54 might be mapped to: | |
| 55 </p> | |
| 56 <pre class="programlisting"> | |
| 57 static public ImageSurface createFromPNG (String filename) throws IOException; | |
| 58 static public ImageSurface createFromPNG (InputStream stream) throws IOException; | |
| 59 public void writeToPNG (String filename) throws IOException; | |
| 60 public void writeToPNG (OutputStream stream) throws IOException; | |
| 61 </pre> | |
| 62 <p> | |
| 63 In many cases, it will be better to | |
| 64 implement the filename version internally | |
| 65 using the stream version, rather than building it on top of the | |
| 66 filename version in C. The reason for this is that will | |
| 67 naturally give a more standard handling of file errors for | |
| 68 the language, as seen in the above Java example, where | |
| 69 <code class="methodname">createFromPNG()</code> is marked as raising | |
| 70 an exception. Propagating exceptions from inside the callback | |
| 71 function to the caller will pose a challenge to the language | |
| 72 binding implementor, since an exception must not propagate | |
| 73 through the Cairo code. A technique that will be useful in | |
| 74 some cases is to catch the exception in the callback, | |
| 75 store the exception object inside a structure pointed to by | |
| 76 <em class="parameter"><code>closure</code></em>, and then rethrow it once | |
| 77 the function returns. | |
| 78 </p> | |
| 79 <p class="remark"><em><span class="remark"> | |
| 80 I'm not sure how to handle this for | |
| 81 <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>. | |
| 82 Other than keep a “exception to rethrow” thread-specific | |
| 83 variable | |
| 84 that is checked after <span class="emphasis"><em>every</em></span> call to a Cairo | |
| 85 function. | |
| 86 </span></em></p> | |
| 87 </div> | |
| 88 <div class="footer"> | |
| 89 <hr>Generated by GTK-Doc V1.27</div> | |
| 90 </body> | |
| 91 </html> |