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