← Back to branch summary

~ubuntu-branches/ubuntu/trusty/glib2.0/trusty-proposed

« back to all changes in this revision

Viewing changes to docs/reference/gio/xml/gmemoryoutputstream.xml

  • Committer: Bazaar Package Importer
  • Author(s): Sebastien Bacher
  • Date: 2010-03-09 11:28:22 UTC
  • mfrom: (3.4.8 experimental)
  • Revision ID: james.westby@ubuntu.com-20100309112822-j4n0v3xbtsup8s97
Tags: 2.23.5-1ubuntu1
* Resync on Debian
* debian/patches/01_gettext-desktopfiles.patch:
  - updated to use gettext for X-GNOME-Fullname too
* debian/patches/71_gio_launch_handler.patch:
  - new gio default launch handle feature required for wncksync
* debian/control.in, 
  debian/patches/80-gtester-subunit.patch:
  - gtester-report subunit support
* debian/libglib2.0-0.symbols:
  - updated the symbols list for the gio launcher handler
* debian/rules:
  - don't break build on test suite errors, debian recently activated this but
    the build breaks even when there is no error in the testsuite

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/reference/gio/xml/gmemoryoutputstream.xml
 
1
<?xml version="1.0"?>
 
2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
 
3
               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
 
4
<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
 
5
<!ENTITY version SYSTEM "version.xml">
 
6
]>
 
7
<refentry id="GMemoryOutputStream">
 
8
<refmeta>
 
9
<refentrytitle role="top_of_page" id="GMemoryOutputStream.top_of_page">GMemoryOutputStream</refentrytitle>
 
10
<manvolnum>3</manvolnum>
 
11
<refmiscinfo>GIO Library</refmiscinfo>
 
12
</refmeta>
 
13
 
 
14
<refnamediv>
 
15
<refname>GMemoryOutputStream</refname>
 
16
<refpurpose>Streaming output operations on memory chunks</refpurpose>
 
17
</refnamediv>
 
18
 
 
19
<refsynopsisdiv id="GMemoryOutputStream.synopsis" role="synopsis">
 
20
<title role="synopsis.title">Synopsis</title>
 
21
 
 
22
<synopsis>
 
23
 
 
24
#include &lt;gio/gio.h&gt;
 
25
 
 
26
<link linkend="gpointer">gpointer</link>            (<link linkend="GReallocFunc">*GReallocFunc</link>)                     (<link linkend="gpointer">gpointer</link> data,
 
27
                                                         <link linkend="gsize">gsize</link> size);
 
28
                    <link linkend="GMemoryOutputStream-struct">GMemoryOutputStream</link>;
 
29
<link linkend="GOutputStream">GOutputStream</link> *     <link linkend="g-memory-output-stream-new">g_memory_output_stream_new</link>          (<link linkend="gpointer">gpointer</link> data,
 
30
                                                         <link linkend="gsize">gsize</link> size,
 
31
                                                         <link linkend="GReallocFunc">GReallocFunc</link> realloc_function,
 
32
                                                         <link linkend="GDestroyNotify">GDestroyNotify</link> destroy_function);
 
33
<link linkend="gpointer">gpointer</link>            <link linkend="g-memory-output-stream-get-data">g_memory_output_stream_get_data</link>     (<link linkend="GMemoryOutputStream">GMemoryOutputStream</link> *ostream);
 
34
<link linkend="gsize">gsize</link>               <link linkend="g-memory-output-stream-get-size">g_memory_output_stream_get_size</link>     (<link linkend="GMemoryOutputStream">GMemoryOutputStream</link> *ostream);
 
35
<link linkend="gsize">gsize</link>               <link linkend="g-memory-output-stream-get-data-size">g_memory_output_stream_get_data_size</link>
 
36
                                                        (<link linkend="GMemoryOutputStream">GMemoryOutputStream</link> *ostream);
 
37
</synopsis>
 
38
</refsynopsisdiv>
 
39
 
 
40
<refsect1 id="GMemoryOutputStream.object-hierarchy" role="object_hierarchy">
 
41
<title role="object_hierarchy.title">Object Hierarchy</title>
 
42
<synopsis>
 
43
  <link linkend="GObject">GObject</link>
 
44
   +----<link linkend="GOutputStream">GOutputStream</link>
 
45
         +----GMemoryOutputStream
 
46
</synopsis>
 
47
</refsect1>
 
48
 
 
49
 
 
50
 
 
51
<refsect1 id="GMemoryOutputStream.implemented-interfaces" role="impl_interfaces">
 
52
<title role="impl_interfaces.title">Implemented Interfaces</title>
 
53
<para>
 
54
GMemoryOutputStream implements
 
55
 <link linkend="GSeekable">GSeekable</link>.</para>
 
56
</refsect1>
 
57
 
 
58
 
 
59
<refsect1 id="GMemoryOutputStream.properties" role="properties">
 
60
<title role="properties.title">Properties</title>
 
61
<synopsis>
 
62
  &quot;<link linkend="GMemoryOutputStream--data">data</link>&quot;                     <link linkend="gpointer">gpointer</link>              : Read / Write / Construct Only
 
63
  &quot;<link linkend="GMemoryOutputStream--data-size">data-size</link>&quot;                <link linkend="gulong">gulong</link>                : Read
 
64
  &quot;<link linkend="GMemoryOutputStream--destroy-function">destroy-function</link>&quot;         <link linkend="gpointer">gpointer</link>              : Read / Write / Construct Only
 
65
  &quot;<link linkend="GMemoryOutputStream--realloc-function">realloc-function</link>&quot;         <link linkend="gpointer">gpointer</link>              : Read / Write / Construct Only
 
66
  &quot;<link linkend="GMemoryOutputStream--size">size</link>&quot;                     <link linkend="gulong">gulong</link>                : Read / Write / Construct Only
 
67
</synopsis>
 
68
</refsect1>
 
69
 
 
70
 
 
71
 
 
72
<refsect1 id="GMemoryOutputStream.description" role="desc">
 
73
<title role="desc.title">Description</title>
 
74
<para>
 
75
<link linkend="GMemoryOutputStream"><type>GMemoryOutputStream</type></link> is a class for using arbitrary
 
76
memory chunks as output for GIO streaming output operations.</para>
 
77
<para>
 
78
</para>
 
79
</refsect1>
 
80
 
 
81
<refsect1 id="GMemoryOutputStream.details" role="details">
 
82
<title role="details.title">Details</title>
 
83
<refsect2 id="GReallocFunc" role="function">
 
84
<title>GReallocFunc ()</title>
 
85
<indexterm zone="GReallocFunc"><primary sortas="ReallocFunc">GReallocFunc</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link>            (*GReallocFunc)                     (<link linkend="gpointer">gpointer</link> data,
 
86
                                                         <link linkend="gsize">gsize</link> size);</programlisting>
 
87
<para>
 
88
Changes the size of the memory block pointed to by <parameter>data</parameter> to
 
89
<parameter>size</parameter> bytes.
 
90
</para>
 
91
<para>
 
92
The function should have the same semantics as <link linkend="realloc"><function>realloc()</function></link>.</para>
 
93
<para>
 
94
</para><variablelist role="params">
 
95
<varlistentry><term><parameter>data</parameter>&#160;:</term>
 
96
<listitem><simpara> memory block to reallocate
 
97
</simpara></listitem></varlistentry>
 
98
<varlistentry><term><parameter>size</parameter>&#160;:</term>
 
99
<listitem><simpara> size to reallocate <parameter>data</parameter> to
 
100
</simpara></listitem></varlistentry>
 
101
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a pointer to the reallocated memory
 
102
</simpara></listitem></varlistentry>
 
103
</variablelist></refsect2>
 
104
<refsect2 id="GMemoryOutputStream-struct" role="struct">
 
105
<title>GMemoryOutputStream</title>
 
106
<indexterm zone="GMemoryOutputStream-struct"><primary sortas="MemoryOutputStream">GMemoryOutputStream</primary></indexterm><programlisting>typedef struct _GMemoryOutputStream GMemoryOutputStream;</programlisting>
 
107
<para>
 
108
Implements <link linkend="GOutputStream"><type>GOutputStream</type></link> for arbitrary memory chunks.</para>
 
109
<para>
 
110
</para></refsect2>
 
111
<refsect2 id="g-memory-output-stream-new" role="function">
 
112
<title>g_memory_output_stream_new ()</title>
 
113
<indexterm zone="g-memory-output-stream-new"><primary sortas="memory_output_stream_new">g_memory_output_stream_new</primary></indexterm><programlisting><link linkend="GOutputStream">GOutputStream</link> *     g_memory_output_stream_new          (<link linkend="gpointer">gpointer</link> data,
 
114
                                                         <link linkend="gsize">gsize</link> size,
 
115
                                                         <link linkend="GReallocFunc">GReallocFunc</link> realloc_function,
 
116
                                                         <link linkend="GDestroyNotify">GDestroyNotify</link> destroy_function);</programlisting>
 
117
<para>
 
118
Creates a new <link linkend="GMemoryOutputStream"><type>GMemoryOutputStream</type></link>.
 
119
</para>
 
120
<para>
 
121
If <parameter>data</parameter> is non-<link linkend="NULL--CAPS"><literal>NULL</literal></link>, the stream  will use that for its internal storage.
 
122
If <parameter>realloc_fn</parameter> is non-<link linkend="NULL--CAPS"><literal>NULL</literal></link>, it will be used for resizing the internal
 
123
storage when necessary. To construct a fixed-size output stream,
 
124
pass <link linkend="NULL--CAPS"><literal>NULL</literal></link> as <parameter>realloc_fn</parameter>.
 
125
</para>
 
126
<para>
 
127
<informalexample><programlisting>
 
128
/&ast; a stream that can grow &ast;/
 
129
stream = g_memory_output_stream_new (NULL, 0, realloc, free);
 
130
 
 
131
/&ast; another stream that can grow &ast;/
 
132
stream2 = g_memory_output_stream_new (NULL, 0, g_realloc, g_free);
 
133
 
 
134
/&ast; a fixed-size stream &ast;/
 
135
data = malloc (200);
 
136
stream3 = g_memory_output_stream_new (data, 200, NULL, free);
 
137
</programlisting></informalexample></para>
 
138
<para>
 
139
</para><variablelist role="params">
 
140
<varlistentry><term><parameter>data</parameter>&#160;:</term>
 
141
<listitem><simpara> pointer to a chunk of memory to use, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
 
142
</simpara></listitem></varlistentry>
 
143
<varlistentry><term><parameter>size</parameter>&#160;:</term>
 
144
<listitem><simpara> the size of <parameter>data</parameter>
 
145
</simpara></listitem></varlistentry>
 
146
<varlistentry><term><parameter>realloc_function</parameter>&#160;:</term>
 
147
<listitem><simpara> a function with <link linkend="realloc"><function>realloc()</function></link> semantics (like <link linkend="g-realloc"><function>g_realloc()</function></link>)
 
148
    to be called when <parameter>data</parameter> needs to be grown, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
 
149
</simpara></listitem></varlistentry>
 
150
<varlistentry><term><parameter>destroy_function</parameter>&#160;:</term>
 
151
<listitem><simpara> a function to be called on <parameter>data</parameter> when the stream is
 
152
    finalized, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
 
153
</simpara></listitem></varlistentry>
 
154
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> A newly created <link linkend="GMemoryOutputStream"><type>GMemoryOutputStream</type></link> object.
 
155
</simpara></listitem></varlistentry>
 
156
</variablelist></refsect2>
 
157
<refsect2 id="g-memory-output-stream-get-data" role="function">
 
158
<title>g_memory_output_stream_get_data ()</title>
 
159
<indexterm zone="g-memory-output-stream-get-data"><primary sortas="memory_output_stream_get_data">g_memory_output_stream_get_data</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link>            g_memory_output_stream_get_data     (<link linkend="GMemoryOutputStream">GMemoryOutputStream</link> *ostream);</programlisting>
 
160
<para>
 
161
Gets any loaded data from the <parameter>ostream</parameter>.
 
162
</para>
 
163
<para>
 
164
Note that the returned pointer may become invalid on the next
 
165
write or truncate operation on the stream.</para>
 
166
<para>
 
167
</para><variablelist role="params">
 
168
<varlistentry><term><parameter>ostream</parameter>&#160;:</term>
 
169
<listitem><simpara> a <link linkend="GMemoryOutputStream"><type>GMemoryOutputStream</type></link>
 
170
</simpara></listitem></varlistentry>
 
171
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> pointer to the stream's data
 
172
</simpara></listitem></varlistentry>
 
173
</variablelist></refsect2>
 
174
<refsect2 id="g-memory-output-stream-get-size" role="function">
 
175
<title>g_memory_output_stream_get_size ()</title>
 
176
<indexterm zone="g-memory-output-stream-get-size"><primary sortas="memory_output_stream_get_size">g_memory_output_stream_get_size</primary></indexterm><programlisting><link linkend="gsize">gsize</link>               g_memory_output_stream_get_size     (<link linkend="GMemoryOutputStream">GMemoryOutputStream</link> *ostream);</programlisting>
 
177
<para>
 
178
Gets the size of the currently allocated data area (availible from
 
179
<link linkend="g-memory-output-stream-get-data"><function>g_memory_output_stream_get_data()</function></link>). If the stream isn't
 
180
growable (no realloc was passed to <link linkend="g-memory-output-stream-new"><function>g_memory_output_stream_new()</function></link>) then
 
181
this is the maximum size of the stream and further writes
 
182
will return <link linkend="G-IO-ERROR-NO-SPACE--CAPS"><literal>G_IO_ERROR_NO_SPACE</literal></link>.
 
183
</para>
 
184
<para>
 
185
Note that for growable streams the returned size may become invalid on
 
186
the next write or truncate operation on the stream.
 
187
</para>
 
188
<para>
 
189
If you want the number of bytes currently written to the stream, use
 
190
<link linkend="g-memory-output-stream-get-data-size"><function>g_memory_output_stream_get_data_size()</function></link>.</para>
 
191
<para>
 
192
</para><variablelist role="params">
 
193
<varlistentry><term><parameter>ostream</parameter>&#160;:</term>
 
194
<listitem><simpara> a <link linkend="GMemoryOutputStream"><type>GMemoryOutputStream</type></link>
 
195
</simpara></listitem></varlistentry>
 
196
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the number of bytes allocated for the data buffer
 
197
</simpara></listitem></varlistentry>
 
198
</variablelist></refsect2>
 
199
<refsect2 id="g-memory-output-stream-get-data-size" role="function" condition="since:2.18">
 
200
<title>g_memory_output_stream_get_data_size ()</title>
 
201
<indexterm zone="g-memory-output-stream-get-data-size" role="2.18"><primary sortas="memory_output_stream_get_data_size">g_memory_output_stream_get_data_size</primary></indexterm><programlisting><link linkend="gsize">gsize</link>               g_memory_output_stream_get_data_size
 
202
                                                        (<link linkend="GMemoryOutputStream">GMemoryOutputStream</link> *ostream);</programlisting>
 
203
<para>
 
204
Returns the number of bytes from the start up
 
205
to including the last byte written in the stream
 
206
that has not been truncated away.</para>
 
207
<para>
 
208
</para><variablelist role="params">
 
209
<varlistentry><term><parameter>ostream</parameter>&#160;:</term>
 
210
<listitem><simpara> a <link linkend="GMemoryOutputStream"><type>GMemoryOutputStream</type></link>
 
211
</simpara></listitem></varlistentry>
 
212
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the number of bytes written to the stream
 
213
 
 
214
</simpara></listitem></varlistentry>
 
215
</variablelist><para role="since">Since 2.18</para></refsect2>
 
216
 
 
217
</refsect1>
 
218
<refsect1 id="GMemoryOutputStream.property-details" role="property_details">
 
219
<title role="property_details.title">Property Details</title>
 
220
<refsect2 id="GMemoryOutputStream--data" role="property"><title>The <literal>&quot;data&quot;</literal> property</title>
 
221
<indexterm zone="GMemoryOutputStream--data" role="2.24"><primary sortas="MemoryOutputStream:data">GMemoryOutputStream:data</primary></indexterm><programlisting>  &quot;data&quot;                     <link linkend="gpointer">gpointer</link>              : Read / Write / Construct Only</programlisting>
 
222
<para>
 
223
Pointer to buffer where data will be written.</para>
 
224
<para>
 
225
</para><para>Since 2.24</para>
 
226
</refsect2>
 
227
<refsect2 id="GMemoryOutputStream--data-size" role="property"><title>The <literal>&quot;data-size&quot;</literal> property</title>
 
228
<indexterm zone="GMemoryOutputStream--data-size" role="2.24"><primary sortas="MemoryOutputStream:data-size">GMemoryOutputStream:data-size</primary></indexterm><programlisting>  &quot;data-size&quot;                <link linkend="gulong">gulong</link>                : Read</programlisting>
 
229
<para>
 
230
Size of data written to the buffer.</para>
 
231
<para>
 
232
</para><para>Since 2.24</para>
 
233
</refsect2>
 
234
<refsect2 id="GMemoryOutputStream--destroy-function" role="property"><title>The <literal>&quot;destroy-function&quot;</literal> property</title>
 
235
<indexterm zone="GMemoryOutputStream--destroy-function" role="2.24"><primary sortas="MemoryOutputStream:destroy-function">GMemoryOutputStream:destroy-function</primary></indexterm><programlisting>  &quot;destroy-function&quot;         <link linkend="gpointer">gpointer</link>              : Read / Write / Construct Only</programlisting>
 
236
<para>
 
237
Function called with the buffer as argument when the stream is destroyed.</para>
 
238
<para>
 
239
</para><para>Since 2.24</para>
 
240
</refsect2>
 
241
<refsect2 id="GMemoryOutputStream--realloc-function" role="property"><title>The <literal>&quot;realloc-function&quot;</literal> property</title>
 
242
<indexterm zone="GMemoryOutputStream--realloc-function" role="2.24"><primary sortas="MemoryOutputStream:realloc-function">GMemoryOutputStream:realloc-function</primary></indexterm><programlisting>  &quot;realloc-function&quot;         <link linkend="gpointer">gpointer</link>              : Read / Write / Construct Only</programlisting>
 
243
<para>
 
244
Function with realloc semantics called to enlarge the buffer.</para>
 
245
<para>
 
246
</para><para>Since 2.24</para>
 
247
</refsect2>
 
248
<refsect2 id="GMemoryOutputStream--size" role="property"><title>The <literal>&quot;size&quot;</literal> property</title>
 
249
<indexterm zone="GMemoryOutputStream--size" role="2.24"><primary sortas="MemoryOutputStream:size">GMemoryOutputStream:size</primary></indexterm><programlisting>  &quot;size&quot;                     <link linkend="gulong">gulong</link>                : Read / Write / Construct Only</programlisting>
 
250
<para>
 
251
Current size of the data buffer.</para>
 
252
<para>
 
253
</para><para>Since 2.24</para>
 
254
</refsect2>
 
255
</refsect1>
 
256
 
 
257
 
 
258
 
 
259
<refsect1 id="GMemoryOutputStream.see-also">
 
260
<title>See Also</title>
 
261
#GMemoryInputStream
 
262
</refsect1>
 
263
 
 
264
</refentry>