The buffer interface exports a model where an object can expose its
internal data as a set of chunks of data, where each chunk is
specified as a pointer/length pair. These chunks are called
segments and are presumed to be non-contiguous in memory.
If an object does not export the buffer interface, then its
tp_as_buffer member in the PyTypeObject structure
should be NULL. Otherwise, the tp_as_buffer will point to
a PyBufferProcs structure.
Note: It is very important that your
PyTypeObject structure uses Py_TPFLAGS_DEFAULT for
the value of the tp_flags member rather than 0. This
tells the Python runtime that your PyBufferProcs structure
contains the bf_getcharbuffer slot. Older versions of Python
did not have this member, so a new Python interpreter using an old
extension needs to be able to test for its presence before using it.
Structure used to hold the function pointers which define an
implementation of the buffer protocol.
The first slot is bf_getreadbuffer, of type
getreadbufferproc. If this slot is NULL, then the object
does not support reading from the internal data. This is
non-sensical, so implementors should fill this in, but callers should
test that the slot contains a non-NULL value.
The next slot is bf_getwritebuffer having type
getwritebufferproc. This slot may be NULL if the object
does not allow writing into its returned buffers.
The third slot is bf_getsegcount, with type
getsegcountproc. This slot must not be NULL and is used to
inform the caller how many segments the object contains. Simple
objects such as PyString_Type and
PyBuffer_Type objects contain a single segment.
The last slot is bf_getcharbuffer, of type
getcharbufferproc. This slot will only be present if the
Py_TPFLAGS_HAVE_GETCHARBUFFER flag is present in the
tp_flags field of the object's PyTypeObject. Before using
this slot, the caller should test whether it is present by using the
PyType_HasFeature()function.
If present, it may be NULL, indicating that the object's contents
cannot be used as 8-bit characters.
The slot function may also raise an error if the object's contents
cannot be interpreted as 8-bit characters. For example, if the object
is an array which is configured to hold floating point values, an
exception may be raised if a caller attempts to use
bf_getcharbuffer to fetch a sequence of 8-bit characters.
This notion of exporting the internal buffers as ``text'' is used to
distinguish between objects that are binary in nature, and those which
have character-based content.
Note: The current policy seems to state that these characters
may be multi-byte characters. This implies that a buffer size of
N does not mean there are N characters present.
Flag bit set in the type structure to indicate that the
bf_getcharbuffer slot is known. This being set does not
indicate that the object supports the buffer interface or that the
bf_getcharbuffer slot is non-NULL.
Return a pointer to a readable segment of the buffer. This function
is allowed to raise an exception, in which case it must return
-1. The segment which is passed must be zero or
positive, and strictly less than the number of segments returned by
the bf_getsegcount slot function. On success, it returns the
length of the buffer memory, and sets *ptrptr to a
pointer to that memory.
Return a pointer to a writable memory buffer in *ptrptr,
and the length of that segment as the function return value.
The memory buffer must correspond to buffer segment segment.
Must return -1 and set an exception on error.
TypeError should be raised if the object only supports
read-only buffers, and SystemError should be raised when
segment specifies a segment that doesn't exist.
Return the number of memory segments which comprise the buffer. If
lenp is not NULL, the implementation must report the sum of the
sizes (in bytes) of all segments in *lenp.
The function cannot fail.