Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
2 | <html> | |
3 | <head> | |
4 | <link rel="STYLESHEET" href="api.css" type='text/css' /> | |
5 | <link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" /> | |
6 | <link rel='start' href='../index.html' title='Python Documentation Index' /> | |
7 | <link rel="first" href="api.html" title='Python/C API Reference Manual' /> | |
8 | <link rel='contents' href='contents.html' title="Contents" /> | |
9 | <link rel='index' href='genindex.html' title='Index' /> | |
10 | <link rel='last' href='about.html' title='About this document...' /> | |
11 | <link rel='help' href='about.html' title='About this document...' /> | |
12 | <link rel="next" href="supporting-iteration.html" /> | |
13 | <link rel="prev" href="sequence-structs.html" /> | |
14 | <link rel="parent" href="newTypes.html" /> | |
15 | <link rel="next" href="supporting-iteration.html" /> | |
16 | <meta name='aesop' content='information' /> | |
17 | <title>10.7 Buffer Object Structures </title> | |
18 | </head> | |
19 | <body> | |
20 | <DIV CLASS="navigation"> | |
21 | <div id='top-navigation-panel' xml:id='top-navigation-panel'> | |
22 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> | |
23 | <tr> | |
24 | <td class='online-navigation'><a rel="prev" title="10.6 Sequence Object Structures" | |
25 | href="sequence-structs.html"><img src='../icons/previous.png' | |
26 | border='0' height='32' alt='Previous Page' width='32' /></A></td> | |
27 | <td class='online-navigation'><a rel="parent" title="10. Object Implementation Support" | |
28 | href="newTypes.html"><img src='../icons/up.png' | |
29 | border='0' height='32' alt='Up One Level' width='32' /></A></td> | |
30 | <td class='online-navigation'><a rel="next" title="10.8 Supporting the Iterator" | |
31 | href="supporting-iteration.html"><img src='../icons/next.png' | |
32 | border='0' height='32' alt='Next Page' width='32' /></A></td> | |
33 | <td align="center" width="100%">Python/C API Reference Manual</td> | |
34 | <td class='online-navigation'><a rel="contents" title="Table of Contents" | |
35 | href="contents.html"><img src='../icons/contents.png' | |
36 | border='0' height='32' alt='Contents' width='32' /></A></td> | |
37 | <td class='online-navigation'><img src='../icons/blank.png' | |
38 | border='0' height='32' alt='' width='32' /></td> | |
39 | <td class='online-navigation'><a rel="index" title="Index" | |
40 | href="genindex.html"><img src='../icons/index.png' | |
41 | border='0' height='32' alt='Index' width='32' /></A></td> | |
42 | </tr></table> | |
43 | <div class='online-navigation'> | |
44 | <b class="navlabel">Previous:</b> | |
45 | <a class="sectref" rel="prev" href="sequence-structs.html">10.6 Sequence Object Structures</A> | |
46 | <b class="navlabel">Up:</b> | |
47 | <a class="sectref" rel="parent" href="newTypes.html">10. Object Implementation Support</A> | |
48 | <b class="navlabel">Next:</b> | |
49 | <a class="sectref" rel="next" href="supporting-iteration.html">10.8 Supporting the Iterator</A> | |
50 | </div> | |
51 | <hr /></div> | |
52 | </DIV> | |
53 | <!--End of Navigation Panel--> | |
54 | ||
55 | <H1><A NAME="SECTION0012700000000000000000"></A><A NAME="buffer-structs"></A> | |
56 | <BR> | |
57 | 10.7 Buffer Object Structures | |
58 | </H1> | |
59 | ||
60 | <P> | |
61 | The buffer interface exports a model where an object can expose its | |
62 | internal data as a set of chunks of data, where each chunk is | |
63 | specified as a pointer/length pair. These chunks are called | |
64 | <i class="dfn">segments</i> and are presumed to be non-contiguous in memory. | |
65 | ||
66 | <P> | |
67 | If an object does not export the buffer interface, then its | |
68 | <tt class="member">tp_as_buffer</tt> member in the <tt class="ctype">PyTypeObject</tt> structure | |
69 | should be <tt class="constant">NULL</tt>. Otherwise, the <tt class="member">tp_as_buffer</tt> will point to | |
70 | a <tt class="ctype">PyBufferProcs</tt> structure. | |
71 | ||
72 | <P> | |
73 | <span class="note"><b class="label">Note:</b> | |
74 | It is very important that your <tt class="ctype">PyTypeObject</tt> structure | |
75 | uses <tt class="constant">Py_TPFLAGS_DEFAULT</tt> for the value of the | |
76 | <tt class="member">tp_flags</tt> member rather than <code>0</code>. This tells the Python | |
77 | runtime that your <tt class="ctype">PyBufferProcs</tt> structure contains the | |
78 | <tt class="member">bf_getcharbuffer</tt> slot. Older versions of Python did not have | |
79 | this member, so a new Python interpreter using an old extension needs | |
80 | to be able to test for its presence before using it.</span> | |
81 | ||
82 | <P> | |
83 | <dl><dt><b><tt class="ctype"><a id='l2h-1008' xml:id='l2h-1008'>PyBufferProcs</a></tt></b></dt> | |
84 | <dd> | |
85 | Structure used to hold the function pointers which define an | |
86 | implementation of the buffer protocol. | |
87 | ||
88 | <P> | |
89 | The first slot is <tt class="member">bf_getreadbuffer</tt>, of type | |
90 | <tt class="ctype">getreadbufferproc</tt>. If this slot is <tt class="constant">NULL</tt>, then the object | |
91 | does not support reading from the internal data. This is | |
92 | non-sensical, so implementors should fill this in, but callers | |
93 | should test that the slot contains a non-<tt class="constant">NULL</tt> value. | |
94 | ||
95 | <P> | |
96 | The next slot is <tt class="member">bf_getwritebuffer</tt> having type | |
97 | <tt class="ctype">getwritebufferproc</tt>. This slot may be <tt class="constant">NULL</tt> if the object | |
98 | does not allow writing into its returned buffers. | |
99 | ||
100 | <P> | |
101 | The third slot is <tt class="member">bf_getsegcount</tt>, with type | |
102 | <tt class="ctype">getsegcountproc</tt>. This slot must not be <tt class="constant">NULL</tt> and is used | |
103 | to inform the caller how many segments the object contains. Simple | |
104 | objects such as <tt class="ctype">PyString_Type</tt> and <tt class="ctype">PyBuffer_Type</tt> | |
105 | objects contain a single segment. | |
106 | ||
107 | <P> | |
108 | The last slot is <tt class="member">bf_getcharbuffer</tt>, of type | |
109 | <tt class="ctype">getcharbufferproc</tt>. This slot will only be present if the | |
110 | <tt class="constant">Py_TPFLAGS_HAVE_GETCHARBUFFER</tt> flag is present in the | |
111 | <tt class="member">tp_flags</tt> field of the object's <tt class="ctype">PyTypeObject</tt>. | |
112 | Before using this slot, the caller should test whether it is present | |
113 | by using the | |
114 | <tt class="cfunction">PyType_HasFeature()</tt><a id='l2h-1014' xml:id='l2h-1014'></a> | |
115 | function. If present, it may be <tt class="constant">NULL</tt>, indicating that the object's | |
116 | contents cannot be used as <em>8-bit characters</em>. | |
117 | The slot function may also raise an error if the object's contents | |
118 | cannot be interpreted as 8-bit characters. For example, if the | |
119 | object is an array which is configured to hold floating point | |
120 | values, an exception may be raised if a caller attempts to use | |
121 | <tt class="member">bf_getcharbuffer</tt> to fetch a sequence of 8-bit characters. | |
122 | This notion of exporting the internal buffers as ``text'' is used to | |
123 | distinguish between objects that are binary in nature, and those | |
124 | which have character-based content. | |
125 | ||
126 | <P> | |
127 | <span class="note"><b class="label">Note:</b> | |
128 | The current policy seems to state that these characters | |
129 | may be multi-byte characters. This implies that a buffer size of | |
130 | <var>N</var> does not mean there are <var>N</var> characters present.</span> | |
131 | </dl> | |
132 | ||
133 | <P> | |
134 | <dl><dt><b><tt id='l2h-1009' xml:id='l2h-1009'>Py_TPFLAGS_HAVE_GETCHARBUFFER</tt></b></dt> | |
135 | <dd> | |
136 | Flag bit set in the type structure to indicate that the | |
137 | <tt class="member">bf_getcharbuffer</tt> slot is known. This being set does not | |
138 | indicate that the object supports the buffer interface or that the | |
139 | <tt class="member">bf_getcharbuffer</tt> slot is non-<tt class="constant">NULL</tt>. | |
140 | </dd></dl> | |
141 | ||
142 | <P> | |
143 | <dl><dt><b><tt class="ctype"><a id='l2h-1010' xml:id='l2h-1010'>int (*getreadbufferproc) | |
144 | (PyObject *self, int segment, void **ptrptr)</a></tt></b></dt> | |
145 | <dd> | |
146 | Return a pointer to a readable segment of the buffer. This function | |
147 | is allowed to raise an exception, in which case it must return | |
148 | <code>-1</code>. The <var>segment</var> which is passed must be zero or | |
149 | positive, and strictly less than the number of segments returned by | |
150 | the <tt class="member">bf_getsegcount</tt> slot function. On success, it returns | |
151 | the length of the buffer memory, and sets <code>*<var>ptrptr</var></code> to a | |
152 | pointer to that memory. | |
153 | </dl> | |
154 | ||
155 | <P> | |
156 | <dl><dt><b><tt class="ctype"><a id='l2h-1011' xml:id='l2h-1011'>int (*getwritebufferproc) | |
157 | (PyObject *self, int segment, void **ptrptr)</a></tt></b></dt> | |
158 | <dd> | |
159 | Return a pointer to a writable memory buffer in | |
160 | <code>*<var>ptrptr</var></code>, and the length of that segment as the function | |
161 | return value. The memory buffer must correspond to buffer segment | |
162 | <var>segment</var>. Must return <code>-1</code> and set an exception on | |
163 | error. <tt class="exception">TypeError</tt> should be raised if the object only | |
164 | supports read-only buffers, and <tt class="exception">SystemError</tt> should be | |
165 | raised when <var>segment</var> specifies a segment that doesn't exist. | |
166 | </dl> | |
167 | ||
168 | <P> | |
169 | <dl><dt><b><tt class="ctype"><a id='l2h-1012' xml:id='l2h-1012'>int (*getsegcountproc) | |
170 | (PyObject *self, int *lenp)</a></tt></b></dt> | |
171 | <dd> | |
172 | Return the number of memory segments which comprise the buffer. If | |
173 | <var>lenp</var> is not <tt class="constant">NULL</tt>, the implementation must report the sum of | |
174 | the sizes (in bytes) of all segments in <code>*<var>lenp</var></code>. | |
175 | The function cannot fail. | |
176 | </dl> | |
177 | ||
178 | <P> | |
179 | <dl><dt><b><tt class="ctype"><a id='l2h-1013' xml:id='l2h-1013'>int (*getcharbufferproc) | |
180 | (PyObject *self, int segment, const char **ptrptr)</a></tt></b></dt> | |
181 | <dd> | |
182 | Return the size of the memory buffer in <var>ptrptr</var> for segment | |
183 | <var>segment</var>. <code>*<var>ptrptr</var></code> is set to the memory buffer. | |
184 | </dl> | |
185 | ||
186 | <P> | |
187 | ||
188 | <DIV CLASS="navigation"> | |
189 | <div class='online-navigation'> | |
190 | <p></p><hr /> | |
191 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> | |
192 | <tr> | |
193 | <td class='online-navigation'><a rel="prev" title="10.6 Sequence Object Structures" | |
194 | href="sequence-structs.html"><img src='../icons/previous.png' | |
195 | border='0' height='32' alt='Previous Page' width='32' /></A></td> | |
196 | <td class='online-navigation'><a rel="parent" title="10. Object Implementation Support" | |
197 | href="newTypes.html"><img src='../icons/up.png' | |
198 | border='0' height='32' alt='Up One Level' width='32' /></A></td> | |
199 | <td class='online-navigation'><a rel="next" title="10.8 Supporting the Iterator" | |
200 | href="supporting-iteration.html"><img src='../icons/next.png' | |
201 | border='0' height='32' alt='Next Page' width='32' /></A></td> | |
202 | <td align="center" width="100%">Python/C API Reference Manual</td> | |
203 | <td class='online-navigation'><a rel="contents" title="Table of Contents" | |
204 | href="contents.html"><img src='../icons/contents.png' | |
205 | border='0' height='32' alt='Contents' width='32' /></A></td> | |
206 | <td class='online-navigation'><img src='../icons/blank.png' | |
207 | border='0' height='32' alt='' width='32' /></td> | |
208 | <td class='online-navigation'><a rel="index" title="Index" | |
209 | href="genindex.html"><img src='../icons/index.png' | |
210 | border='0' height='32' alt='Index' width='32' /></A></td> | |
211 | </tr></table> | |
212 | <div class='online-navigation'> | |
213 | <b class="navlabel">Previous:</b> | |
214 | <a class="sectref" rel="prev" href="sequence-structs.html">10.6 Sequence Object Structures</A> | |
215 | <b class="navlabel">Up:</b> | |
216 | <a class="sectref" rel="parent" href="newTypes.html">10. Object Implementation Support</A> | |
217 | <b class="navlabel">Next:</b> | |
218 | <a class="sectref" rel="next" href="supporting-iteration.html">10.8 Supporting the Iterator</A> | |
219 | </div> | |
220 | </div> | |
221 | <hr /> | |
222 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> | |
223 | </DIV> | |
224 | <!--End of Navigation Panel--> | |
225 | <ADDRESS> | |
226 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. | |
227 | </ADDRESS> | |
228 | </BODY> | |
229 | </HTML> |